1---
2name: pnpm-configuration
3description: Configuration options via pnpm-workspace.yaml and .npmrc settings
4---
5 
6# pnpm Configuration
7 
8pnpm uses two main configuration files: `pnpm-workspace.yaml` for workspace and pnpm-specific settings, and `.npmrc` for npm-compatible and pnpm-specific settings.
9 
10## pnpm-workspace.yaml
11 
12The recommended location for pnpm-specific configurations. Place at project root.
13 
14```yaml
15# Define workspace packages
16packages:
17  - 'packages/*'
18  - 'apps/*'
19  - '!**/test/**'  # Exclude pattern
20 
21# Catalog for shared dependency versions
22catalog:
23  react: ^18.2.0
24  typescript: ~5.3.0
25 
26# Named catalogs for different dependency groups
27catalogs:
28  react17:
29    react: ^17.0.2
30    react-dom: ^17.0.2
31  react18:
32    react: ^18.2.0
33    react-dom: ^18.2.0
34 
35# Override resolutions (preferred location)
36overrides:
37  lodash: ^4.17.21
38  'foo@^1.0.0>bar': ^2.0.0
39 
40# pnpm settings (alternative to .npmrc)
41settings:
42  auto-install-peers: true
43  strict-peer-dependencies: false
44  link-workspace-packages: true
45  prefer-workspace-packages: true
46  shared-workspace-lockfile: true
47```
48 
49## .npmrc Settings
50 
51pnpm reads settings from `.npmrc` files. Create at project root or user home.
52 
53### Common pnpm Settings
54 
55```ini
56# Automatically install peer dependencies
57auto-install-peers=true
58 
59# Fail on peer dependency issues
60strict-peer-dependencies=false
61 
62# Hoist patterns for dependencies
63public-hoist-pattern[]=*types*
64public-hoist-pattern[]=*eslint*
65shamefully-hoist=false
66 
67# Store location
68store-dir=~/.pnpm-store
69 
70# Virtual store location  
71virtual-store-dir=node_modules/.pnpm
72 
73# Lockfile settings
74lockfile=true
75prefer-frozen-lockfile=true
76 
77# Side effects cache (speeds up rebuilds)
78side-effects-cache=true
79 
80# Registry settings
81registry=https://registry.npmjs.org/
82@myorg:registry=https://npm.myorg.com/
83```
84 
85### Workspace Settings
86 
87```ini
88# Link workspace packages
89link-workspace-packages=true
90 
91# Prefer workspace packages over registry
92prefer-workspace-packages=true
93 
94# Single lockfile for all packages
95shared-workspace-lockfile=true
96 
97# Save prefix for workspace dependencies
98save-workspace-protocol=rolling
99```
100 
101### Node.js Settings
102 
103```ini
104# Use specific Node.js version
105use-node-version=20.10.0
106 
107# Node.js version file
108node-version-file=.nvmrc
109 
110# Manage Node.js versions
111manage-package-manager-versions=true
112```
113 
114### Security Settings
115 
116```ini
117# Ignore specific scripts
118ignore-scripts=false
119 
120# Allow specific build scripts
121onlyBuiltDependencies[]=esbuild
122onlyBuiltDependencies[]=sharp
123 
124# Package extensions for missing peer deps
125package-extensions[foo@1].peerDependencies.bar=*
126```
127 
128## Configuration Hierarchy
129 
130Settings are read in order (later overrides earlier):
131 
1321. `/etc/npmrc` - Global config
1332. `~/.npmrc` - User config  
1343. `<project>/.npmrc` - Project config
1354. Environment variables: `npm_config_<key>=<value>`
1365. `pnpm-workspace.yaml` settings field
137 
138## Environment Variables
139 
140```bash
141# Set config via env
142npm_config_registry=https://registry.npmjs.org/
143 
144# pnpm-specific env vars
145PNPM_HOME=~/.local/share/pnpm
146```
147 
148## Package.json Fields
149 
150pnpm reads specific fields from `package.json`:
151 
152```json
153{
154  "pnpm": {
155    "overrides": {
156      "lodash": "^4.17.21"
157    },
158    "peerDependencyRules": {
159      "ignoreMissing": ["@babel/*"],
160      "allowedVersions": {
161        "react": "17 || 18"
162      }
163    },
164    "neverBuiltDependencies": ["fsevents"],
165    "onlyBuiltDependencies": ["esbuild"],
166    "allowedDeprecatedVersions": {
167      "request": "*"
168    },
169    "patchedDependencies": {
170      "[email protected]": "patches/[email protected]"
171    }
172  }
173}
174```
175 
176## Key Differences from npm/yarn
177 
1781. **Strict by default**: No phantom dependencies
1792. **Workspace protocol**: `workspace:*` for local packages
1803. **Catalogs**: Centralized version management
1814. **Content-addressable store**: Shared across projects
182 
183<!-- 
184Source references:
185- https://pnpm.io/pnpm-workspace_yaml
186- https://pnpm.io/npmrc
187- https://pnpm.io/package_json
188-->
189