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.
9 
10## Quick Migration
11 
12### From npm
13 
14```bash
15# Remove npm lockfile and node_modules
16rm -rf node_modules package-lock.json
17 
18# Install with pnpm
19pnpm install
20```
21 
22### From Yarn
23 
24```bash
25# Remove yarn lockfile and node_modules
26rm -rf node_modules yarn.lock
27 
28# Install with pnpm
29pnpm install
30```
31 
32### Import Existing Lockfile
33 
34pnpm can import existing lockfiles:
35 
36```bash
37# Import from npm or yarn lockfile
38pnpm import
39 
40# This creates pnpm-lock.yaml from:
41# - package-lock.json (npm)
42# - yarn.lock (yarn)
43# - npm-shrinkwrap.json (npm)
44```
45 
46## Handling Common Issues
47 
48### Phantom Dependencies
49 
50pnpm is strict about dependencies. If code imports a package not in `package.json`, it will fail.
51 
52**Problem:**
53```js
54// Works with npm (hoisted), fails with pnpm
55import lodash from 'lodash' // Not in dependencies, installed by another package
56```
57 
58**Solution:** Add missing dependencies explicitly:
59```bash
60pnpm add lodash
61```
62 
63### Missing Peer Dependencies
64 
65pnpm reports peer dependency issues by default.
66 
67**Option 1:** Let pnpm auto-install:
68```ini
69# .npmrc (default in pnpm v8+)
70auto-install-peers=true
71```
72 
73**Option 2:** Install manually:
74```bash
75pnpm add react react-dom
76```
77 
78**Option 3:** Suppress warnings if acceptable:
79```json
80{
81  "pnpm": {
82    "peerDependencyRules": {
83      "ignoreMissing": ["react"]
84    }
85  }
86}
87```
88 
89### Symlink Issues
90 
91Some tools don't work with symlinks. Use hoisted mode:
92 
93```ini
94# .npmrc
95node-linker=hoisted
96```
97 
98Or hoist specific packages:
99 
100```ini
101public-hoist-pattern[]=*eslint*
102public-hoist-pattern[]=*babel*
103```
104 
105### Native Module Rebuilds
106 
107If native modules fail, try:
108 
109```bash
110# Rebuild all native modules
111pnpm rebuild
112 
113# Or reinstall
114rm -rf node_modules
115pnpm install
116```
117 
118## Monorepo Migration
119 
120### From npm Workspaces
121 
1221. Create `pnpm-workspace.yaml`:
123   ```yaml
124   packages:
125     - 'packages/*'
126   ```
127 
1282. Update internal dependencies to use workspace protocol:
129   ```json
130   {
131     "dependencies": {
132       "@myorg/utils": "workspace:^"
133     }
134   }
135   ```
136 
1373. Install:
138   ```bash
139   rm -rf node_modules packages/*/node_modules package-lock.json
140   pnpm install
141   ```
142 
143### From Yarn Workspaces
144 
1451. Remove Yarn-specific files:
146   ```bash
147   rm yarn.lock .yarnrc.yml
148   rm -rf .yarn
149   ```
150 
1512. Create `pnpm-workspace.yaml` matching `workspaces` in package.json:
152   ```yaml
153   packages:
154     - 'packages/*'
155   ```
156 
1573. Update `package.json` - remove Yarn workspace config if not needed:
158   ```json
159   {
160     // Remove "workspaces" field (optional, pnpm uses pnpm-workspace.yaml)
161   }
162   ```
163 
1644. Convert workspace references:
165   ```json
166   // From Yarn
167   "@myorg/utils": "*"
168   
169   // To pnpm
170   "@myorg/utils": "workspace:*"
171   ```
172 
173### From Lerna
174 
175pnpm can replace Lerna for most use cases:
176 
177```bash
178# Lerna: run script in all packages
179lerna run build
180 
181# pnpm equivalent
182pnpm -r run build
183 
184# Lerna: run in specific package
185lerna run build --scope=@myorg/app
186 
187# pnpm equivalent  
188pnpm --filter @myorg/app run build
189 
190# Lerna: publish
191lerna publish
192 
193# pnpm: use changesets instead
194pnpm add -Dw @changesets/cli
195pnpm changeset
196pnpm changeset version
197pnpm publish -r
198```
199 
200## Configuration Migration
201 
202### .npmrc Settings
203 
204Most npm/Yarn settings work in pnpm's `.npmrc`:
205 
206```ini
207# Registry settings (same as npm)
208registry=https://registry.npmjs.org/
209@myorg:registry=https://npm.myorg.com/
210 
211# Auth tokens (same as npm)
212//registry.npmjs.org/:_authToken=${NPM_TOKEN}
213 
214# pnpm-specific additions
215auto-install-peers=true
216strict-peer-dependencies=false
217```
218 
219### Scripts Migration
220 
221Most scripts work unchanged. Update pnpm-specific patterns:
222 
223```json
224{
225  "scripts": {
226    // npm: recursive scripts
227    "build:all": "npm run build --workspaces",
228    // pnpm: use -r flag
229    "build:all": "pnpm -r run build",
230    
231    // npm: run in specific workspace  
232    "dev:app": "npm run dev -w packages/app",
233    // pnpm: use --filter
234    "dev:app": "pnpm --filter @myorg/app run dev"
235  }
236}
237```
238 
239## CI/CD Migration
240 
241Update CI configuration:
242 
243```yaml
244# Before (npm)
245- run: npm ci
246 
247# After (pnpm)
248- uses: pnpm/action-setup@v4
249- run: pnpm install --frozen-lockfile
250```
251 
252Add to `package.json` for Corepack:
253```json
254{
255  "packageManager": "[email protected]"
256}
257```
258 
259## Gradual Migration
260 
261For large projects, migrate gradually:
262 
2631. **Start with CI**: Use pnpm in CI, keep npm/yarn locally
2642. **Add pnpm-lock.yaml**: Run `pnpm import` to create lockfile
2653. **Test thoroughly**: Ensure builds work with pnpm
2664. **Update documentation**: Update README, CONTRIBUTING
2675. **Remove old files**: Delete old lockfiles after team adoption
268 
269## Rollback Plan
270 
271If migration causes issues:
272 
273```bash
274# Remove pnpm files
275rm -rf node_modules pnpm-lock.yaml pnpm-workspace.yaml
276 
277# Restore npm
278npm install
279 
280# Or restore Yarn
281yarn install
282```
283 
284Keep old lockfile in git history for easy rollback.
285 
286<!-- 
287Source references:
288- https://pnpm.io/installation
289- https://pnpm.io/cli/import
290- https://pnpm.io/limitations
291-->
292