1---
2name: pnpm-peer-dependencies
3description: Handling peer dependencies with auto-install and resolution rules
4---
5 
6# pnpm Peer Dependencies
7 
8pnpm has strict peer dependency handling by default. It provides configuration options to control how peer dependencies are resolved and reported.
9 
10## Auto-Install Peer Dependencies
11 
12By default, pnpm automatically installs peer dependencies:
13 
14```ini
15# .npmrc (default is true since pnpm v8)
16auto-install-peers=true
17```
18 
19When enabled, pnpm automatically adds missing peer dependencies based on the best matching version.
20 
21## Strict Peer Dependencies
22 
23Control whether peer dependency issues cause errors:
24 
25```ini
26# Fail on peer dependency issues (default: false)
27strict-peer-dependencies=true
28```
29 
30When strict, pnpm will fail if:
31- Peer dependency is missing
32- Installed version doesn't match required range
33 
34## Peer Dependency Rules
35 
36Configure peer dependency behavior in `package.json`:
37 
38```json
39{
40  "pnpm": {
41    "peerDependencyRules": {
42      "ignoreMissing": ["@babel/*", "eslint"],
43      "allowedVersions": {
44        "react": "17 || 18"
45      },
46      "allowAny": ["@types/*"]
47    }
48  }
49}
50```
51 
52### ignoreMissing
53 
54Suppress warnings for missing peer dependencies:
55 
56```json
57{
58  "pnpm": {
59    "peerDependencyRules": {
60      "ignoreMissing": [
61        "@babel/*",
62        "eslint",
63        "webpack"
64      ]
65    }
66  }
67}
68```
69 
70Use patterns:
71- `"react"` - exact package name
72- `"@babel/*"` - all packages in scope
73- `"*"` - all packages (not recommended)
74 
75### allowedVersions
76 
77Allow specific versions that would otherwise cause warnings:
78 
79```json
80{
81  "pnpm": {
82    "peerDependencyRules": {
83      "allowedVersions": {
84        "react": "17 || 18",
85        "webpack": "4 || 5",
86        "@types/react": "*"
87      }
88    }
89  }
90}
91```
92 
93### allowAny
94 
95Allow any version for specified peer dependencies:
96 
97```json
98{
99  "pnpm": {
100    "peerDependencyRules": {
101      "allowAny": ["@types/*", "eslint"]
102    }
103  }
104}
105```
106 
107## Adding Peer Dependencies via Hooks
108 
109Use `.pnpmfile.cjs` to add missing peer dependencies:
110 
111```js
112// .pnpmfile.cjs
113function readPackage(pkg, context) {
114  // Add missing peer dependency
115  if (pkg.name === 'problematic-package') {
116    pkg.peerDependencies = {
117      ...pkg.peerDependencies,
118      react: '*'
119    }
120  }
121  return pkg
122}
123 
124module.exports = {
125  hooks: {
126    readPackage
127  }
128}
129```
130 
131## Peer Dependencies in Workspaces
132 
133Workspace packages can satisfy peer dependencies:
134 
135```json
136// packages/app/package.json
137{
138  "dependencies": {
139    "react": "^18.2.0",
140    "@myorg/components": "workspace:^"
141  }
142}
143 
144// packages/components/package.json  
145{
146  "peerDependencies": {
147    "react": "^17.0.0 || ^18.0.0"
148  }
149}
150```
151 
152The workspace `app` provides `react` which satisfies `components`' peer dependency.
153 
154## Common Scenarios
155 
156### Monorepo with Shared React
157 
158```yaml
159# pnpm-workspace.yaml
160catalog:
161  react: ^18.2.0
162  react-dom: ^18.2.0
163```
164 
165```json
166// packages/ui/package.json
167{
168  "peerDependencies": {
169    "react": "^18.0.0",
170    "react-dom": "^18.0.0"
171  }
172}
173 
174// apps/web/package.json
175{
176  "dependencies": {
177    "react": "catalog:",
178    "react-dom": "catalog:",
179    "@myorg/ui": "workspace:^"
180  }
181}
182```
183 
184### Suppress ESLint Plugin Warnings
185 
186```json
187{
188  "pnpm": {
189    "peerDependencyRules": {
190      "ignoreMissing": [
191        "eslint",
192        "@typescript-eslint/parser"
193      ]
194    }
195  }
196}
197```
198 
199### Allow Multiple Major Versions
200 
201```json
202{
203  "pnpm": {
204    "peerDependencyRules": {
205      "allowedVersions": {
206        "webpack": "4 || 5",
207        "postcss": "7 || 8"
208      }
209    }
210  }
211}
212```
213 
214## Debugging Peer Dependencies
215 
216```bash
217# See why a package is installed
218pnpm why <package>
219 
220# List all peer dependency warnings
221pnpm install --reporter=append-only 2>&1 | grep -i peer
222 
223# Check dependency tree
224pnpm list --depth=Infinity
225```
226 
227## Best Practices
228 
2291. **Enable auto-install-peers** for convenience (default in pnpm v8+)
230 
2312. **Use peerDependencyRules** instead of ignoring all warnings
232 
2333. **Document suppressed warnings** explaining why they're safe
234 
2354. **Keep peer deps ranges wide** in libraries:
236   ```json
237   {
238     "peerDependencies": {
239       "react": "^17.0.0 || ^18.0.0"
240     }
241   }
242   ```
243 
2445. **Test with different peer versions** if you support multiple majors
245 
246<!-- 
247Source references:
248- https://pnpm.io/package_json#pnpmpeerdependencyrules
249- https://pnpm.io/npmrc#auto-install-peers
250-->
251