Package manager migration guide

15 min

Follow this guide to migrate your Optimizely Connect Plaform (OCP) app from Yarn 1 to other packager managers, such as npm, pnpm, Bun, or Yarn Berry v3+.

Prerequisites

You must install OCP CLI v2. See the OCP CLI v2 migration guide.

Your application must be running on Node.js 22+. See the OCP CLI v2 migration guide.

Developers and CI/CD pipelines must be using OCP CLI v2 before making changes to your app's package.json.

📘 Note Package manager migration is only supported for apps on Node.js 22+ runtime. Apps using older runtines should continue using Yarn 1.

Supported package managers

OCP CLI v2 supports Yarn, including Yarn Berry v3+, npm, pnpm, and Bun. The build system automatically detects your package manager from your project configuration, including the lock files, the packageManager field in package.json, and more.

Migrate to the package managers

Implement the following steps to migrate to other package managers:

(Optional) Remove install scripts from package.json

OCP CLI v2 automatically uses the correct package manager for your app, eliminating the need for separate install scripts in package.json. You can remove redundant install scripts, though keeping them does not cause conflicts.

The following displays an example before removing install scripts:

{
  "scripts": {
    "build": "yarn && ...",
    "validate": "yarn build && ..."
  }
}

The following displays an example if you are still using Yarn as a package manager:

{
  "scripts": {
    "build": "...",
    "validate": "yarn build && ..."
  }
}

📘 Note OCP CLI's default app templates intentionally omit package manager-specific shorthand build scripts. This design choice prevents confusion and simplifies switching package managers, as scripts like validate already encompass all necessary build, test, and lint steps. You can convert these to shorthand commands if preferred.

Remove grpc-boom from resolutions

The grpc-boom resolution is no longer necessary for applications running on Node.js 22 and newer. Remove it from your package.json.

🚧 Important This change applies only to apps using Node.js 22+. Applications on older runtimes still require this resolution.

The following displays an example before removing grpc-boom from resolutions:

{
  "resolutions": {
    "grpc-boom": "^3.0.11"
  }
}

The following displays an example after removing it:

{
  // Remove the resolutions block entirely if grpc-boom was the only entry
}

Update validation script

Replace the manual validation script path with the ocp-app-sdk validate command.

📘 Note The ocp-app-sdk CLI is only available in @zaiusinc/[email protected] or newer versions, which require Node.js 22+ runtime.

The following displays an example before replacing the manual validation script:

{
  "scripts": {
    "validate": "yarn build && yarn lint && yarn test && cross-env LOG_LEVEL=never node node_modules/@zaiusinc/app-sdk/dist/app/validation/runValidation.js"
  }
}

The following displays an example after replacing it:

{
  "scripts": {
    "validate": "yarn build && yarn lint && yarn test && cross-env LOG_LEVEL=NEVER ocp-app-sdk validate"
  }
}

Switch to your preferred package manager

To switch from Yarn to another package manager, complete the following:

Delete the existing yarn.lock file.

Initialize your new package manager, which creates the following lock file:

# For npm
npm install

# For pnpm
pnpm install

# For bun
bun install

# For Yarn Berry
yarn set version berry
yarn install

(Optional) Explicitly define your preferred package manager by adding the packageManager field to your package.json file.

Update scripts in package.json

Update your package.json scripts to use your preferred package manager's commands:

Yarn 1	npm	pnpm	Bun
yarn	npm install	pnpm install	bun install
yarn build	npm run build	pnpm build	bun run build
yarn test	npm test	pnpm test	bun test
yarn lint	npm run lint	pnpm lint	bun run lint

Example for npm

{
  "scripts": {
    "validate": "npm run build && npm run lint && npm test && cross-env LOG_LEVEL=NEVER ocp-app-sdk validate"
  }
}

Example for pnpm

{
  "scripts": {
    "validate": "pnpm build && pnpm lint && pnpm test && cross-env LOG_LEVEL=NEVER ocp-app-sdk validate"
  }
}

📘 Note If migrating to Yarn Berry (v3+), you can continue using existing yarn commands as they remain compatible.

Validate your app

Run the following validation command to ensure full functionality. If it runs successfully, your app is ready to use the new package manager.

ocp app validate

Quickstart to migration

Confirm you are running OCP CLI v2. Your ocp --version should display v2.x.x.

Ensure your application is configured for Node.js 22 or a newer runtime.

Ensure that all team members and CI/CD pipelines are using OCP CLI v2.

(Optional) Remove redundant install scripts from your package.json file.

Delete the grpc-boom entry from your resolutions block in package.json.

Modify your validation script to use ocp-app-sdk validate.

Migrate to your preferred package manager:

Delete your existing yarn.lock or equivalent file.

Run the install command for your preferred package manager (for example, npm install, pnpm install, yarn install).

Update any scripts in package.json to reflect the commands of your newly adopted package manager.

Run ocp app validate to confirm all changes are working correctly.