1---
2name: migration-to-pnpm
3description: Migrating from npm or Yarn to pnpm with minimal friction
4---
5 
6# Migration to pnpm
7 
8Guide for migrating existing projects from npm or Yarn to pnpm, plus upgrading pnpm v10 → v11.
9 
10## Upgrading pnpm v10 → v11
11 
12v11 changes how configuration is read. Most of it is mechanical — run the codemod:
13 
14```bash
15cd /path/to/project
16pnpx codemod run pnpm-v10-to-v11
17```
18 
19The codemod automatically:
20 
21- **Moves `package.json#pnpm` settings into `pnpm-workspace.yaml`** (the `pnpm` field is no longer read).
22- **Splits `.npmrc`**: only auth/registry settings stay in `.npmrc`; every other key moves to `pnpm-workspace.yaml` as **camelCase** (e.g. `node-linker` → `nodeLinker`). Per-subproject `.npmrc` files become `packageConfigs["<name>"]`.
23- **Consolidates build settings** (`onlyBuiltDependencies`, `neverBuiltDependencies`, `ignoredBuiltDependencies`, `onlyBuiltDependenciesFile`) into one `allowBuilds: { name: true|false }` map.
24- **Replaces** `managePackageManagerVersions`/`packageManagerStrict`/`packageManagerStrictVersion` with `pmOnFail: download|ignore|warn|error`.
25- **Renames** `allowNonAppliedPatches` → `allowUnusedPatches`, `auditConfig.ignoreCves` → `auditConfig.ignoreGhsas`.
26- **Converts** `useNodeVersion` → `devEngines.runtime`, and bumps `packageManager`.
27 
28Manual follow-ups (not automatable):
29 
30- Convert `CVE-…` IDs to `GHSA-…` in `auditConfig.ignoreGhsas`.
31- `ignorePatchFailures` removed — failed patches now always throw.
32- `npm_config_*` env vars → `pnpm_config_*` (CI, shell profiles, Docker).
33- `pnpm link <name>` → use a path (`pnpm link ./foo`); `pnpm link --global` → `pnpm add -g .`.
34- `pnpm install -g` (no args) and `pnpm server` removed.
35- A `package.json` script named `clean`/`setup`/`deploy`/`rebuild` now shadows the built-in — use `pnpm pm <name>` for the built-in.
36 
37## Migrating from npm / Yarn
38 
39## Quick Migration
40 
41### From npm
42 
43```bash
44# Remove npm lockfile and node_modules
45rm -rf node_modules package-lock.json
46 
47# Install with pnpm
48pnpm install
49```
50 
51### From Yarn
52 
53```bash
54# Remove yarn lockfile and node_modules
55rm -rf node_modules yarn.lock
56 
57# Install with pnpm
58pnpm install
59```
60 
61### Import Existing Lockfile
62 
63pnpm can import existing lockfiles:
64 
65```bash
66# Import from npm or yarn lockfile
67pnpm import
68 
69# This creates pnpm-lock.yaml from:
70# - package-lock.json (npm)
71# - yarn.lock (yarn)
72# - npm-shrinkwrap.json (npm)
73```
74 
75## Handling Common Issues
76 
77### Phantom Dependencies
78 
79pnpm is strict about dependencies. If code imports a package not in `package.json`, it will fail.
80 
81**Problem:**
82```js
83// Works with npm (hoisted), fails with pnpm
84import lodash from 'lodash' // Not in dependencies, installed by another package
85```
86 
87**Solution:** Add missing dependencies explicitly:
88```bash
89pnpm add lodash
90```
91 
92### Missing Peer Dependencies
93 
94pnpm reports peer dependency issues by default.
95 
96**Option 1:** Let pnpm auto-install (default in v8+):
97```yaml title="pnpm-workspace.yaml"
98autoInstallPeers: true
99```
100 
101**Option 2:** Install manually:
102```bash
103pnpm add react react-dom
104```
105 
106**Option 3:** Suppress warnings if acceptable:
107```yaml title="pnpm-workspace.yaml"
108peerDependencyRules:
109  ignoreMissing:
110    - react
111```
112 
113### Symlink Issues
114 
115Some tools don't work with symlinks. Use hoisted mode:
116 
117```yaml title="pnpm-workspace.yaml"
118nodeLinker: hoisted
119```
120 
121Or hoist specific packages:
122 
123```yaml title="pnpm-workspace.yaml"
124publicHoistPattern:
125  - '*eslint*'
126  - '*babel*'
127```
128 
129### Native Module Rebuilds
130 
131If native modules fail, try:
132 
133```bash
134# Rebuild all native modules
135pnpm rebuild
136 
137# Or reinstall
138rm -rf node_modules
139pnpm install
140```
141 
142## Monorepo Migration
143 
144### From npm Workspaces
145 
1461. Create `pnpm-workspace.yaml`:
147   ```yaml
148   packages:
149     - 'packages/*'
150   ```
151 
1522. Update internal dependencies to use workspace protocol:
153   ```json
154   {
155     "dependencies": {
156       "@myorg/utils": "workspace:^"
157     }
158   }
159   ```
160 
1613. Install:
162   ```bash
163   rm -rf node_modules packages/*/node_modules package-lock.json
164   pnpm install
165   ```
166 
167### From Yarn Workspaces
168 
1691. Remove Yarn-specific files:
170   ```bash
171   rm yarn.lock .yarnrc.yml
172   rm -rf .yarn
173   ```
174 
1752. Create `pnpm-workspace.yaml` matching `workspaces` in package.json:
176   ```yaml
177   packages:
178     - 'packages/*'
179   ```
180 
1813. Update `package.json` - remove Yarn workspace config if not needed:
182   ```json
183   {
184     // Remove "workspaces" field (optional, pnpm uses pnpm-workspace.yaml)
185   }
186   ```
187 
1884. Convert workspace references:
189   ```json
190   // From Yarn
191   "@myorg/utils": "*"
192   
193   // To pnpm
194   "@myorg/utils": "workspace:*"
195   ```
196 
197### From Lerna
198 
199pnpm can replace Lerna for most use cases:
200 
201```bash
202# Lerna: run script in all packages
203lerna run build
204 
205# pnpm equivalent
206pnpm -r run build
207 
208# Lerna: run in specific package
209lerna run build --scope=@myorg/app
210 
211# pnpm equivalent  
212pnpm --filter @myorg/app run build
213 
214# Lerna: publish
215lerna publish
216 
217# pnpm: use changesets instead
218pnpm add -Dw @changesets/cli
219pnpm changeset
220pnpm changeset version
221pnpm publish -r
222```
223 
224## Configuration Migration
225 
226Keep only **auth/registry** in `.npmrc`; put everything else in `pnpm-workspace.yaml` (camelCase).
227 
228```ini title=".npmrc (auth only, gitignored)"
229//registry.npmjs.org/:_authToken=${NPM_TOKEN}
230//npm.myorg.com/:_authToken=${MYORG_TOKEN}
231```
232 
233```yaml title="pnpm-workspace.yaml"
234registries:
235  default: https://registry.npmjs.org/
236  '@myorg': https://npm.myorg.com/
237autoInstallPeers: true
238strictPeerDependencies: false
239```
240 
241### Scripts Migration
242 
243Most scripts work unchanged. Update pnpm-specific patterns:
244 
245```json
246{
247  "scripts": {
248    // npm: recursive scripts
249    "build:all": "npm run build --workspaces",
250    // pnpm: use -r flag
251    "build:all": "pnpm -r run build",
252    
253    // npm: run in specific workspace  
254    "dev:app": "npm run dev -w packages/app",
255    // pnpm: use --filter
256    "dev:app": "pnpm --filter @myorg/app run dev"
257  }
258}
259```
260 
261## CI/CD Migration
262 
263Update CI configuration:
264 
265```yaml
266# Before (npm)
267- run: npm ci
268 
269# After (pnpm)
270- uses: pnpm/action-setup@v4
271- run: pnpm install --frozen-lockfile   # or: pnpm ci
272```
273 
274Add to `package.json` for Corepack:
275```json
276{
277  "packageManager": "[email protected]"
278}
279```
280 
281## Gradual Migration
282 
283For large projects, migrate gradually:
284 
2851. **Start with CI**: Use pnpm in CI, keep npm/yarn locally
2862. **Add pnpm-lock.yaml**: Run `pnpm import` to create lockfile
2873. **Test thoroughly**: Ensure builds work with pnpm
2884. **Update documentation**: Update README, CONTRIBUTING
2895. **Remove old files**: Delete old lockfiles after team adoption
290 
291## Rollback Plan
292 
293If migration causes issues:
294 
295```bash
296# Remove pnpm files
297rm -rf node_modules pnpm-lock.yaml pnpm-workspace.yaml
298 
299# Restore npm
300npm install
301 
302# Or restore Yarn
303yarn install
304```
305 
306Keep old lockfile in git history for easy rollback.
307 
308<!--
309Source references:
310- https://pnpm.io/migration
311- https://pnpm.io/cli/import
312- https://pnpm.io/configuring
313-->
314 
315