---
title: Package manager migration guide
slug: optimizely-connect-platform/docs/package-manager-migration
docTags: 
createdAt: 2026-07-23T12:37:04.247Z
---

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](docId:7UYu9f1rF2CBbgKe8sP6I).
- Your application must be running on Node.js 22+. See the [OCP CLI v2 migration guide](docId:7UYu9f1rF2CBbgKe8sP6I).
- Developers and CI/CD pipelines must be using OCP CLI v2 before making changes to your app's `package.json`.

:::hint{type="info"}
**📘 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:

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

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

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

:::hint{type="info"}
**📘 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`.

:::hint{type="warning"}
**🚧 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:

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

The following displays an example after removing it:

```json
{
  // 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.

:::hint{type="info"}
**📘 Note**
The `ocp-app-sdk` CLI is only available in `@zaiusinc/app-sdk@3.x.x` or newer versions, which require Node.js 22+ runtime.
:::

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

```json
{
  "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:

```json
{
  "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:

1. Delete the existing `yarn.lock` file.
2. Initialize your new package manager, which creates the following lock file:

```bash
# For npm
npm install

# For pnpm
pnpm install

# For bun
bun install

# For Yarn Berry
yarn set version berry
yarn install
```

4. (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**

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

**Example for pnpm**

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

:::hint{type="info"}
**📘 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.

```bash
ocp app validate
```

## Quickstart to migration

1. Confirm you are running OCP CLI v2. Your `ocp --version` should display v2.x.x.
2. Ensure your application is configured for Node.js 22 or a newer runtime.
3. Ensure that all team members and CI/CD pipelines are using OCP CLI v2.
4. (Optional) Remove redundant install scripts from your `package.json` file.
5. Delete the `grpc-boom` entry from your `resolutions` block in `package.json`.
6. Modify your validation script to use `ocp-app-sdk validate`.
7. Migrate to your preferred package manager:
   1. Delete your existing `yarn.lock` or equivalent file.
   2. Run the install command for your preferred package manager (for example, `npm install`, `pnpm install`, `yarn install`).
8. Update any scripts in `package.json` to reflect the commands of your newly adopted package manager.
9. Run `ocp app validate` to confirm all changes are working correctly.