---
title: Modernize Node22 engine dependencies
slug: optimizely-connect-platform/docs/node22-engine-dependencies-modernization
docTags: 
createdAt: 2026-07-23T12:37:04.527Z
---

This article outlines the process for migrating an existing Optimizely Connect Platform (OCP) application to the `node22` runtime with updated Node.js dependencies, ensuring compatibility with the latest OCP features and improved performance.

## Prerequisites

An existing OCP app that uses the `node22` runtime with `@zaiusinc/app-sdk` dependency in `2.x.x` version. Verify the runtime version in the `app.yml` file and the `@zaiusinc/app-sdk` version in the `package.json` file.

## Why should you migrate?

OCP supports two primary SDK versions for the `node22` engine, `2.x.x` and `3.x.x`. While the `2.x.x` SDK version remains supported, migrating your application `3.x.x` offers several advantages:

- **Modernized dependencies** – Benefit from simplified Node.js dependencies, including a transition from `node-fetch` library to native `fetch` methods.
- **Enhanced unit testing** – Achieve faster and more reliable unit tests through migration to `vitest`. This is an optional step.
- **Access to new features** – Access new features exclusive to `3.x.x`. Bug and security fixes are continued for `2.x.x` version.

## Migrate OCP app to `3.x.x` major SDK version

Complete the following steps to migrate your OCP app to the `3.x.x` major SDK version:

### Upgrade required dependencies

- Upgrade libraries to their major `3.x.x` major versions. The `--ignore-engines` flag is necessary to temporarily bypass engine checks during installation.

```javascript
yarn add --ignore-engines "@zaiusinc/app-sdk@3.3.2" "@zaiusinc/node-sdk@3.0.0" "@zaiusinc/eslint-config-presets@^3.0.0"  
```

- Remove the `node-fetch` dependency and its type definitions.

```bash
yarn remove --ignore-engines node-fetch 
yarn remove --ignore-engines @types/node-fetch
```

- Migrate to the native `fetch` method if your application code uses the `node-fetch` library. The native `fetch` method is a near drop-in replacement of `node-fetch` library, requiring minimal code changes.
- Remove all existing ESLint-related dependencies from your `package.json` file. Ignore errors about modules not specified in the `package.json` file. The new version of `@zaiusinc/eslint-config-presets` library includes the necessary dependencies for OCP apps, simplifying the dependencies in your `package.json` file.

```bash
yarn remove --ignore-engines @eslint/compat
yarn remove --ignore-engines @stylistic/eslint-plugin
yarn remove --ignore-engines @typescript-eslint/eslint-plugin
yarn remove --ignore-engines @typescript-eslint/parser
yarn remove --ignore-engines eslint
yarn remove --ignore-engines eslint-plugin-import
yarn remove --ignore-engines eslint-plugin-jsdoc
yarn remove --ignore-engines eslint-plugin-prefer-arrow
yarn remove --ignore-engines eslint-plugin-react
yarn remove --ignore-engines tslint
yarn remove --ignore-engines @typescript-eslint/eslint-plugin-tslint 
```

### Check third-party dependencies and compatibilities

- Remove `yarn.lock` and `node_modules`, then reinstall dependencies to rebuild them.

```bash
rm yarn.lock
rm -rf node_modules
yarn install
```

:::Paragraph{listStyleType="disc" indent="2"}
If the command succeeds, it means your dependencies are compatible with Node.js 22.
:::

:::Paragraph{listStyleType="disc" indent="2"}
If it fails, you must upgrade or replace incompatible third-party dependencies. Use `yarn add --ignore-engines [--dev] "<dependency>@<compatible_version>"` individually or manually edit the `package.json` file until `yarn install` command succeeds.
:::

- Run `ocp app validate` to upgrade both `@zaiusinc/app-sdk` and `@zaiusinc/node-sdk` to the versions currently used by OCP. This command also builds and validates your app.

```bash
ocp app validate
```

- Approve the changes if the command prompts you to upgrade both `@zaiusinc/app-sdk` and `@zaiusinc/node-sdk` to the latest versions.

## Typical migration errors

Implement the following solutions for typical errors related to ESLint, TypeScript, or Jest during your OCP app migration to the `node22` runtime:

### Resolve compilation errors

Address and fix compilation errors caused by third-party dependency upgrades individually.

### Address third-party dependency conflicts

Upgrade third-party dependencies to a compatible version if they conflict with `@zaiusinc/app-sdk` or `@zaiusinc/node-sdk` sub-dependencies.

## (Optional) Upgrade related dependencies

Consider the following optional steps to upgrade related dependencies to common compatible versions. Skip to [Clean up and validate](docId:5dSvlziVGLApBZw1gKvXN) if your app is functional after the initial migration steps.

### Upgrade other dev-dependencies used by OCP

- Upgrade other development depdencies to versions compatible with Node.js 22 and `app-sdk` `v3.x.x`. OCP has transitioned from `copyfiles` to `cpy-cli` for improved performance. Replace `copyfile` with `cpy-cli` package in your deveopment dependencies.

```bash
yarn add --dev "cpy-cli@^6.0.0"
yarn remove --ignore-engines copyfiles
```

- Modify the `build` script in your `package.json` file to use `cpy` instead of `copyfiles`. The updated `build` script should resemble the following example:

```json
"build": "yarn && npx rimraf remove dist && npx tsc && cpy app.yml dist && cpy --up 1 \"src/**/*.{yml,yaml}\" dist",
```

- Run the `ocp app validate` command to verify these changes. This command should run successfully. If an error occurs, it likely indicates a version conflict with a third-party dependency. Remove these conflicts individually.

```bash
ocp app validate
```

### Migrate to `vitest` from Jest

The `3.x.x` version of OCP SDKs leverages `vitest` instead of Jest. Migrating to `vitest` offers several key benefits, including the following:

- **Improved speed and performance** – `vitest` significantly improves test execution speed, particularly for projects with extensive test suites.
- **Simplified dependencies** – `vitest` provides support for TypeScript and ESM, removing the complex configurations often required by `ts-jest`. This native support enhances test reliability, ensuring that if your app functions, your tests do too.
- **Increased compatibility** – `vitest` is largely compatible with Jest, minimizing the need for extensive test rewrites during migration.

Execute the following steps to migrate to `vitest`:

- Remove the default `Jest` dependencies used by the OCP app. If your application uses custom Jest dependencies, remove them from the `package.json` as well.

```bash
yarn remove --ignore-engines @types/jest
yarn remove --ignore-engines jest
yarn remove --ignore-engines ts-jest
yarn remove --ignore-engines eslint-plugin-jest
```

- Add the `vitest` dependency to your project.

```bash
 yarn add --dev "vitest"
```

- Update the `test` script in your `package.json` file to use `vitest` instead of `jest`. The updated `test` script should resemble the following example:

```json
"test": "npx vitest run --passWithNoTests"
```

- Create a `vitest.config.ts` root folder of your application with the following content:

```typescript
import { defineConfig } from 'vitest/config';

process.env.ZAIUS_ENV = 'test';

// Load test environment variables
import('dotenv').then(dotenv => {
  dotenv.config({ path: '.env.test' });
});

export default defineConfig({
  test: {
    environment: 'node',
    include: ['src/**/*.test.ts'],
    exclude: ['node_modules', 'dist'],
    coverage: {
      provider: 'v8',
      include: ['src/**/*.ts'],
      exclude: ['src/test/**/*', 'src/**/index.ts'],
    },
    globals: true,
  },
});
```

- Modify your `eslint.config.mjs` ESLint configuration by removing references to `jest` and optionally adding the `vitest` linter. Execute the following steps:
  1. Remove the import of the `eslint-plugin-jest` plugin, `import jest from 'eslint-plugin-jest';`
  2. Remove `jest`  from the plugin list.
  3. Remove all custom rules that contain `jest`, for example, `jest/unbound-method`
  4. Optionally, add the `@zaiusinc/eslint-config-presets/vitest.mjs` linter configuration.
     The default configuration file used by OCP app templates should resemble the following example:

```javascript
import node from '@zaiusinc/eslint-config-presets/node.mjs';
import vitest from '@zaiusinc/eslint-config-presets/vitest.mjs';

export default [
  ...node,
  ...vitest,
  {
    files: ['**/*.test.ts'],

    rules: {
      '@typescript-eslint/unbound-method': 'off'
    },
  }];
```

- Migrate your tests to `vitest`. `vitest` is a near drop-in replacement for Jest, but you need to replace references to `jest` with `vitest` in your code. The main changes involve adding `vitest` related imports and replacing `jest` references with `vi` references. Execute the following steps:
  - Import `vitest` dependencies in every test (`*.test.ts`) file.

```typescript
import { vi, beforeEach, afterEach, describe, it, expect } from 'vitest';
```

:::Paragraph{listStyleType="disc" indent="2"}
Perform the following replacements in your code base:
:::

:::Paragraph{listStyleType="disc" indent="3"}
Replace `as jest.Mock` with `as ReturnType<typeof vi.fn>`.
:::

:::Paragraph{listStyleType="disc" indent="3"}
Replace `jest.` with `vi.`.
:::

:::Paragraph{listStyleType="disc" indent="2"}
Automate these replacements using the following commands:
:::

```javascript
find . -name "*.test.ts" -not -path "*/node_modules/*" -exec sed -i '' '1s/^/import { vi, beforeEach, afterEach, describe, it, expect } from "vitest";\n/' {} +

find . -type f \( -name "*.ts" -o -name "*.tsx" \) -not -path "*/node_modules/*" -exec sed -i '' 's/as jest\.Mock/as ReturnType<typeof vi.fn>;/g' {} +

find . -type f \( -name "*.ts" -o -name "*.tsx" \) -not -path "*/node_modules/*" -exec sed -i '' 's/jest\./vi./g' {} +
```

:::Paragraph{listStyleType="disc" indent="2"}
Run `yarn lint --fix` to resolve any linter issues.
:::

```javascript
yarn lint --fix
```

:::Paragraph{listStyleType="disc" indent="2"}
Run `yarn build test` until all compilation issues are resolved and all tests pass. Refer to [the official vitest guide](https://vitest.dev/guide/migration.html#jest) for details.
:::

```javascript
yarn build test
```

:::Paragraph{listStyleType="disc" indent="2"}
Remove `jest.config.js` file.
:::

```javascript
rm jest.config.js
```

- Run `ocp app validate` command to verify the changes:

```bash
ocp app validate
```

- Fix the issues individually if the compilation or tests fail.

## Clean up and validate

Complete the following steps:

- Remove `yarn.lock` and `node.modules`, then reinstall dependencies to ensure a clean build.

```bash
rm yarn.lock
rm -rf node_modules
yarn install
```

- Run a final validation check on your app.

```bash
ocp app validate
```

- Deploy a new `-dev` or `-beta` version of your app to OCP and conduct thorough testing to confirm successful operation.