# pnpm Migration

Migrate your app to the pnpm version Dyad runs

Dyad manages its own copy of pnpm (currently pnpm 11) to install your app's dependencies safely. Some projects — usually apps imported from GitHub or created with older tools — were set up with an older pnpm and carry one or both of:

- a `packageManager` field in `package.json` pinned to pnpm 8 or older  
- a `pnpm-lock.yaml` with a lockfile format older than `9.0`

That combination causes a subtle problem: when Dyad installs your dependencies, pnpm 11 upgrades `pnpm-lock.yaml` to the `9.0` format. But everything _outside_ Dyad — Vercel, GitHub Actions, and teammates using corepack — follows your project's pinned pnpm version, and pnpm 8 cannot read a `9.0` lockfile. The app keeps working inside Dyad while deploys and CI fail with lockfile errors.

The migration fixes this by making everything agree: it updates the `packageManager` pin to the pnpm version Dyad actually runs and rewrites the lockfile to match, in one visible commit.

pnpm 11 requires Node.js 22 or newer. Before you migrate, make sure your local development environment, CI workflow, and deploy platform all run Node 22+. If an external tool is still on Node 18, 20, or 21, Corepack, Vercel, or GitHub Actions can fail before dependencies install because they try to start pnpm 11 on an unsupported Node version.

If your project is pinned to pnpm 9 or 10, you don't need this upgrade — pnpm 9, 10, and 11 all share the `9.0` lockfile format, so nothing breaks.

## Quick upgrade

Dyad provides a one-click upgrade.

Before starting, update any Node version pin for your app and deployment pipeline to Node 22 or newer. This can include `.nvmrc`, `.node-version`, `engines.node` in `package.json`, the Node version configured in Vercel, and the `node-version` used by `actions/setup-node` in GitHub Actions.

Go to the App Details page by clicking on your app name in the top-left corner.

At the bottom of the app details page, you will see an Upgrades section. Look for the upgrade named **Migrate to pnpm 11** and click Upgrade.

Dyad will:

1. Update the `packageManager` field in `package.json` to the pnpm version Dyad runs  
2. Reinstall your dependencies so `pnpm-lock.yaml` is rewritten to the matching format  
3. Commit both files together as `[dyad] migrate to pnpm 11`

If it succeeds and your deploy or CI environment is also on Node 22+, your next deploy and CI run will use the same pnpm major version as Dyad. If you run into an error, follow the manual upgrade steps below.

## Manual upgrade

To do a manual upgrade, open your [Dyad app code directory](/content/docs/faq#where-is-my-code/index.html) in your terminal.

**Use Node 22 or newer**

Switch your local app directory to Node 22+ before installing pnpm 11. Also update any Node version pin that your deploy or CI system reads, such as `.nvmrc`, `.node-version`, `engines.node`, Vercel's Node.js version setting, or `actions/setup-node` in GitHub Actions.

Check your local version:

```
node --version
```

You should see a version starting with `v22.` or higher.

**Install pnpm 11**

```
npm install -g pnpm@latest-11
```

Check that it worked:

```
pnpm --version
```

You should see a version starting with `11.`.

**Update the `packageManager` field in `package.json`**

Replace the old pin (for example `"packageManager": "pnpm@8.15.9"`) with the version you just installed:

```
"packageManager": "pnpm@11.10.0"
```

Use the exact version printed by `pnpm --version`.

**Reinstall dependencies**

```
pnpm install
```

This rewrites `pnpm-lock.yaml` to the `9.0` lockfile format that matches your new pin.

**Commit the changes**

```
git add package.json pnpm-lock.yaml

git commit -m "Migrate to pnpm 11"
```

Commit `package.json` and `pnpm-lock.yaml` together — deploys break when the pin and the lockfile disagree.

## Troubleshooting

**My deploy fails before installing dependencies.** Check the Node.js version used by your deploy platform or CI workflow. pnpm 11 requires Node 22+, so Node 18, 20, or 21 can fail as soon as Corepack or your package manager starts.

**My deploy still fails with a lockfile error.** Make sure the migration commit was pushed, and that your deploy platform isn't pinning its own pnpm version (for example, a `PNPM_VERSION` environment variable on Vercel or a hardcoded version in a GitHub Actions workflow). Any external pin should match the major version in your `packageManager` field.

**`pnpm install` reports ignored build scripts.** That's expected — Dyad only allows dependency build scripts from a curated allow-list. See the warning message for details; your app will work the same way it does inside Dyad.