---
title: Node22 migration guide
slug: data-platform/connect-platform/node22-migration-guide
docTags: 
createdAt: 2026-08-05T20:06:34.006Z
---

This article provides steps to migrate an existing Optimizely Connect Platform (OCP) app to `node22` runtime,
ensuring compatibility with the latest OCP features and performance improvements.

## Prerequisites

An existing OCP app using `node18` runtime. Check the runtime in the `app.yml` file.

## Migrate OCP app to `node22` runtime

Complete the following steps to migrate your OCP app to `node22` runtime:

### Run the correct Node.js version

Ensure you are running the correct Node.js version when migrating the OCP app. The `node22` engine uses Node.js version 22. See the following example:

```bash
node --version
v22.14.0
```

### (Required) Update application configuration

Modify the runtime setting in your `app.yml` file to specify the `node22` runtime.

```yaml
runtime: node22
```

### (Required) Upgrade required dependencies

- Upgrade libraries to required versions. `node22` runtime requires `2.x` versions of `@zaiusinc/app-sdk` and `@zaiusinc/node-sdk` libraries. `--ignore-engines` flag is needed to temporarily bypass engine checks during installation.

```bash
yarn add --ignore-engines "@zaiusinc/app-sdk@2.0.0" "@zaiusinc/node-sdk@2.0.0"
```

- Upgrade Node.js type definitions to a version compatible with Node.js 22. Ignore warnings about unmet peer dependencies during the installation.

```bash
yarn add --dev --ignore-engines "@types/node@^22.15.17"
```

### (Required) Upgrade ESLint

- Upgrade ESLint to v9. OCP `node22` runtime uses ESLint v9. Because ESLint dependencies used by `node18` OCP runtime are not compatible with Node.js version 22, it is required to update ESLint to v9.
- Remove 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 required by the default ESLint configuration used by 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 
yarn remove --ignore-engines @zaiusinc/tslint-presets
```

- Upgrade other ESLint-related dependencies in your app to ESLint v9 and the Node.js v22 compatible version.
- Upgrade `eslint-config-presets` library. `--ignore-engines` flag is needed to temporarily bypass engine checks during installation.

```bash
 yarn add --ignore-engines --dev "@zaiusinc/eslint-config-presets@^3.0.0" "eslint-plugin-jest@^28.11.0"
```

- Use the following default ESLint configuration file used by OCP apps (`eslint.config.mjs`). ESLint v9 introduced a new configuration format that uses `eslint.config.js` or `eslint.config.mjs` files instead of the older `.eslintrc.js` or similar files.

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

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

    plugins: {
      jest,
    },

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

- Create `eslint.config.mjs` file in the root folder of your app with the content from the ESLint configuration file. If you did not customize your ESLint configuration, you can start using the new file. If you customized, you must migrate your old configuration to the new format. You can do this individually or use the ESLint migration script. See [ESLint v9 migration guide](https://eslint.org/docs/latest/use/migrate-to-9.0.0).
  See the following default ESLint configuration file used by OCP apps in the old format. If the content of your existing `.eslintrc.js` file matches the content, you do not have any customizations.

```javascript
module.exports = {
    extends: '@zaiusinc/eslint-config-presets/node',
    overrides: [
        {
          files: ['**/*.test.ts'],
          plugins: ['jest'],
          rules: {
            // you should turn the original rule off *only* for test files
            '@typescript-eslint/unbound-method': 'off',
            'jest/unbound-method': 'error',
          },
        },
    ],
    rules: {
    },
  }
```

- Run linter and automatically fix issues:

```bash
yarn lint --fix
```

If you still face linting issues, fix them individually by changing the code or modifying rules in `eslint.config.mjs` to match your needs.

- Remove old ESLint configuration files (`.eslintrc.js`):

```bash
rm .eslintrc.js
```

### (Required) Check third-party dependencies and compatibilities

- Remove `yarn.lock` and `node_modules` and install dependencies again to rebuild dependencies:

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

If the command succeeds, it means your dependencies are compatible with Node.js 22. If it fails, you must upgrade or replace incompatible third-party dependencies. Do this individually (` yarn add --ignore-engines [--dev] "<dependency>@<compatible_version>"` or by conducting manual edits of `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 changes if the command asks you to upgrade `@zaiusinc/app-sdk` and `@zaiusinc/node-sdk` to the latest versions.

## Typical migration errors

Implement the following solutions to typical errors you might encounter related to ESLint, TypeScript, or Jest while migrating your OCP app to `node22` runtime:

- **Compilation errors caused by third-party dependency upgrade** – Fix the compilation errors individually.
- **Third-party dependencies conflicting with** `@zaiusinc/app-sdk` **or** `@zaiusinc/node-sdk` **sub-dependencies** – Upgrade the dependency to a compatible version.
- **App code incompatible with** `@types/node@22.x.x` –  Fix the code to be compatible with the new type definitions.

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

### Upgrade TypeScript version

- Upgrade your app's TypeScript version to match the runtime version. OCP `node22` runtime uses TypeScript version `5.8.3`. Ignore warnings about unmet peer dependencies during the installation.

```bash
 yarn add --dev "typescript@^5.8.3"
```

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

```bash
ocp app validate
```

- Fix any TypeScript-related issues individually if the command reports them.

### Upgrade other dev-dependencies used by OCP

- Upgrade other dev-dependencies to versions compatible with Node.js 22 and OCP `node22` runtime. To improve performance, OCP migrated from `@atao60/fse-cli` to `cpy-cli` package. Add `cpy-cli` package to your dev-dependencies:

```bash
yarn add --dev "cpy-cli@^6.0.0"
```

- Replace `build` script in your `package.json` file to use `cpy-cli` instead of `@atao60/fse-cli`.
  The updated `build` script must resemble the following example:

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

- Remove unnecessary dependencies. Skip this step if you are still using these packages in your app, and ignore warnings about unmet peer dependencies during the installation.

```bash
yarn remove --ignore-engines @atao60/fse-cli chalk
```

- Upgrade other dev-dependencies to compatible versions. Ignore warnings about unmet peer dependencies during the installation.

```bash
 yarn add --dev "dotenv@^16.5.0" "rimraf@^6.0.1"
```

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

```bash
ocp app validate
```

This command should complete successfully. If an error occurs, it is likely due to a version conflict with a third-party dependency. Resolve these conflicts individually.

### Upgrade Jest

- Run the following command to upgrade Jest and any related packages to version `29.7.0`:

```bash
 yarn add --dev "@types/jest@^29.5.14" "jest@^29.7.0"
```

- 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

- Rebuild dependencies again:

```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 test thoroughly to ensure everything works successfully.