# Migrate a Yarn 4 Project to pnpm, Lockfile and Patches Included

Yes. An agent converts yarn.lock and Yarn patches to pnpm, settles build-script approvals and the node_modules layout, and opens a pull request with tests passing.

[Run this on Rush](https://cloud.getrush.ai/run/migrate-yarn-to-pnpm/yarn/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads everything Yarn owns in the repository before it runs pnpm. In a library like jquense/yup that is more than a lockfile. `package.json` has `"packageManager": "yarn@4.10.0"` with a hash, a `resolutions` block, and a dev dependency on `@4c/rollout` written as a `patch:` reference to `.yarn/patches/@4c-rollout-npm-4.0.2-ab2b6d0bab.patch`. `.yarnrc.yml` sets `nodeLinker: node-modules`. The scripts call `yarn lint`, `yarn testonly`, `yarn tsc`, `yarn rollup` and `yarn build`. `.github/workflows/ci.yml` runs `corepack enable`, `yarn install --frozen-lockfile` and `yarn test`. The agent first records the baseline with Yarn itself: when this page was written, Vitest reported 28 files and 867 tests passed with 2 skipped, and `yarn lint` exited 0.

The conversion has an order. With pnpm 12.16.1, the release current when this page was written, `pnpm import` stops at once with `ERR_PNPM_OTHER_PM_EXPECTED` and the text `This project is configured to use yarn`, until `packageManager` names pnpm. After that one edit it reads `yarn.lock` and writes `pnpm-lock.yaml`. It also rewrites the `patch:` dependency to plain `4.0.2` and creates `pnpm-workspace.yaml` with a `patchedDependencies` entry that points at the existing patch file. The agent compares the two lockfiles by name and version: of the 1,544 registry entries in `yarn.lock`, 62 have no counterpart in the pnpm lockfile, among them `@npmcli/agent`, `cacache` and `exponential-backoff`, and it lists them so a reviewer can confirm nothing in the project imports them.

Installing surfaces two decisions. `pnpm install --frozen-lockfile` exits 1 with `ERR_PNPM_IGNORED_BUILDS`, naming `esbuild@0.25.10` and `hookem@2.0.1`: pnpm does not run a dependency's install script until it is approved, where Yarn built both. `pnpm approve-builds` writes the answer into an `allowBuilds` map in `pnpm-workspace.yaml`. The agent approves esbuild, which Vitest runs on. It denies hookem: that package sets up Git hooks from a `gitHooks` key, and this `package.json` has none, so its script has nothing to install. Both answers are named in the pull request. The second decision is the layout. With pnpm's default isolated `node_modules` the tests give the same 867 passed and 2 skipped, but `pnpm lint` exits 2: ESLint crashes inside the `ts-expect/expect` rule on `test/types/types.ts` with a TypeScript `Debug Failure`. With `nodeLinker: hoisted`, the flat layout Yarn was already configured for, lint exits 0 and the tests are unchanged. The agent sets `hoisted` and records the isolated failure as a follow-up.

One thing cannot be proved in a sandbox, and the agent says which. The patch exists to change the command `@4c/rollout` runs during a release from `yarn install --frozen-lockfile --production=false` to `yarn install --immutable`. The release tool shells out to Yarn, so after the migration `yarn release` would call a package manager the repository no longer uses. The agent rewrites the patch to call `pnpm install --frozen-lockfile`, moves it to `patches/`, and flags that no release was attempted. It then removes `yarn.lock`, `.yarnrc.yml`, `.yarn/` and `resolutions`, and changes the scripts and the workflow to pnpm.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Migrate this repository from Yarn 4 to the latest pnpm. Read package.json, .yarnrc.yml, the first lines of yarn.lock, everything under .yarn, .nvmrc and .github/workflows first, and list every place Yarn is named. Record the baseline with the pinned Yarn: install with the lockfile, run the test and lint scripts, and note which packages Yarn built. Then change packageManager, run pnpm import, and compare yarn.lock with pnpm-lock.yaml by package name and version; list every entry that is missing or resolved to a different version. Carry the Yarn patch over to pnpm's patchedDependencies and read the patch: say what it changes and whether it still makes sense under pnpm. Run pnpm install --frozen-lockfile and deal with whatever it refuses, approving build scripts only for packages you can justify by name. Run the tests and lint under pnpm's default layout; if anything fails that passed under Yarn, try nodeLinker: hoisted, report both results and keep the setting that reproduces the baseline. Replace yarn in the scripts and in the workflow, delete yarn.lock, .yarnrc.yml and .yarn, and do not publish or run a release. Open a pull request with the output of every command and a list of what you could not test.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

A pull request that adds `pnpm-lock.yaml` and `pnpm-workspace.yaml`, moves the patch, edits `package.json` and the workflow, and deletes the Yarn files. The description puts the Yarn baseline beside the pnpm result for install, tests and lint, and shows the two refusals in the order they occurred, `ERR_PNPM_OTHER_PM_EXPECTED` and `ERR_PNPM_IGNORED_BUILDS`, each with the change that cleared it.

The reviewer spends their time on `pnpm-workspace.yaml`, which now holds three choices in a few lines: which packages may run install scripts, which patch applies to which version, and the hoisted layout. Each has a sentence of reasoning in the description. They read the 62 dropped lockfile entries, and the rewritten patch, which is the one edit to behaviour nobody has run. Before merging they try the release command in a dry run, since that path is the part marked untested.

## Run it on every repository still on Yarn

A package-manager move happens once per repository, so run it per repository from a list. For each one, send this body to `POST /o/{org}/sessions` with that repository in `resources` and a `request_id` that is a UUID v5 of its full name. A second pass over the same list then returns the runs already started and does not open a second pull request.

A key runs up to its `max_concurrent` limit at once, four by default, and the rest wait as `queued` and start in order as slots free. Give the key a `webhook_url` and each finished run posts `run.completed` or `run.failed` to it with its `session_url`; reading each session then gives a table of repositories, results and pull request links without polling.

## Why run it on Rush?

Each step of this migration is a command whose refusal tells you what to do next, and the refusals depend on the exact tool versions and the exact dependency tree. The agent has a sandbox with Node, Corepack, the pinned Yarn and the current pnpm, runs the baseline and the migration side by side, and keeps every line both printed. The lint crash under the isolated layout, for instance, appears only after a full install and a full lint, and the run has both.

The work is also wide in a way that is tedious by hand: a lockfile comparison across more than 1,500 entries, a patch to read, scripts and a workflow to edit, and a list of what stays unproven. Handing it over as one run gives back a pull request that states its own gaps, and several repositories can be migrated at once, each in its own sandbox, without one install waiting on another.

## Frequently asked questions

### Does pnpm import keep the versions from yarn.lock?

It reads `yarn.lock`, including the Yarn 4 format, and writes a pnpm lockfile from it without resolving from scratch. The agent still compares the two files entry by entry and reports anything missing or different. In this repository every entry that carried over kept its version, and 62 did not carry over.

### What happens to Yarn patches?

`pnpm import` converts a `patch:` dependency into a `patchedDependencies` entry in `pnpm-workspace.yaml` and leaves the patch file where it was, under `.yarn/patches`. The agent moves it to a neutral directory and reads it, because a patch written for Yarn may itself mention Yarn, as this one does.

### Why does pnpm install fail with ERR_PNPM_IGNORED_BUILDS?

pnpm does not run install scripts of dependencies unless you approve the package, and with a frozen lockfile an unapproved script is an error. `pnpm approve-builds` records each decision as `true` or `false` under `allowBuilds`. The agent approves by name and explains each one, so the list is short and reviewable.

### Should I use the hoisted layout or pnpm's default?

Start from the default and fall back only on evidence. Here the default layout made ESLint crash in a plugin while the tests still passed, and `nodeLinker: hoisted` matched the Yarn baseline on both. The stricter layout is worth a follow-up once the cause of that crash is known.

## More jobs like this: Hand off a long task

- [Move Yii2 Users From a Hardcoded Array to a Database Table](https://getrush.ai/run/move-users-to-database/yii/)
- [Persist Chat History in a Streamlit App](https://getrush.ai/run/persist-chat-history/streamlit/)
- [Make a Chrome Extension Popup Remember Its State](https://getrush.ai/run/persist-popup-state/chrome-extension/)
- [Pin GitHub Actions to Commit SHAs in Your Workflows](https://getrush.ai/run/pin-action-versions/github-actions/)
- [Protect a DynamoDB Global Table and Its KMS Keys from Deletion in an AWS CDK App](https://getrush.ai/run/protect-stateful-resources/aws-cdk/)
- [Protect Databases and Secrets from Accidental Deletion in a Pulumi Program](https://getrush.ai/run/protect-stateful-resources/pulumi/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
