Node22 migration guide

20 min

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:

node --version
v22.14.0

(Required) Update application configuration

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

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.

yarn add --ignore-engines "@zaiusinc/[email protected]" "@zaiusinc/[email protected]"

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

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.

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.

 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.

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. See the default ESLint configuration file used by OCP apps in the old format below. If the content of your existing .eslintrc.js file matches the content, you do not have any customizations.

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:

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):

rm .eslintrc.js

(Required) Check third-party dependencies and compatibilities

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

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 will also build and validate your app.

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/[email protected] – 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.

 yarn add --dev "typescript@^5.8.3"

Run ocp app validate command to verify the changes:

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:

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

Replace the build script in your package.json file to use cpy (from cpy-cli) instead of @atao60/fse-cli. The updated build script must look like the following example:

"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.

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

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

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

Run ocp app validate command to verify the changes:

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:

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

Run ocp app validate command to verify the changes:

ocp app validate

Fix the issues individually if the compilation or tests fail.

Clean up and validate

Rebuild dependencies again:

rm yarn.lock
rm -rf node_modules
yarn install

Run a final validation check on your app:

ocp app validate

Deploy a new -dev or -beta version of your app to OCP and test thoroughly to ensure everything works successfully.