1---
2name: pnpm-hooks
3description: Customize package resolution and dependency behavior with pnpmfile hooks
4---
5 
6# pnpm Hooks
7 
8pnpm provides hooks via `.pnpmfile.cjs` to customize how packages are resolved and their metadata is processed.
9 
10## Setup
11 
12Create `.pnpmfile.cjs` at workspace root:
13 
14```js
15// .pnpmfile.cjs
16function readPackage(pkg, context) {
17  // Modify package metadata
18  return pkg
19}
20 
21function afterAllResolved(lockfile, context) {
22  // Modify lockfile
23  return lockfile
24}
25 
26module.exports = {
27  hooks: {
28    readPackage,
29    afterAllResolved
30  }
31}
32```
33 
34## readPackage Hook
35 
36Called for every package before resolution. Use to modify dependencies, add missing peer deps, or fix broken packages.
37 
38### Add Missing Peer Dependency
39 
40```js
41function readPackage(pkg, context) {
42  if (pkg.name === 'some-broken-package') {
43    pkg.peerDependencies = {
44      ...pkg.peerDependencies,
45      react: '*'
46    }
47    context.log(`Added react peer dep to ${pkg.name}`)
48  }
49  return pkg
50}
51```
52 
53### Override Dependency Version
54 
55```js
56function readPackage(pkg, context) {
57  // Fix all lodash versions
58  if (pkg.dependencies?.lodash) {
59    pkg.dependencies.lodash = '^4.17.21'
60  }
61  if (pkg.devDependencies?.lodash) {
62    pkg.devDependencies.lodash = '^4.17.21'
63  }
64  return pkg
65}
66```
67 
68### Remove Unwanted Dependency
69 
70```js
71function readPackage(pkg, context) {
72  // Remove optional dependency that causes issues
73  if (pkg.optionalDependencies?.fsevents) {
74    delete pkg.optionalDependencies.fsevents
75  }
76  return pkg
77}
78```
79 
80### Replace Package
81 
82```js
83function readPackage(pkg, context) {
84  // Replace deprecated package
85  if (pkg.dependencies?.['old-package']) {
86    pkg.dependencies['new-package'] = pkg.dependencies['old-package']
87    delete pkg.dependencies['old-package']
88  }
89  return pkg
90}
91```
92 
93### Fix Broken Package
94 
95```js
96function readPackage(pkg, context) {
97  // Fix incorrect exports field
98  if (pkg.name === 'broken-esm-package') {
99    pkg.exports = {
100      '.': {
101        import: './dist/index.mjs',
102        require: './dist/index.cjs'
103      }
104    }
105  }
106  return pkg
107}
108```
109 
110## afterAllResolved Hook
111 
112Called after the lockfile is generated. Use for post-resolution modifications.
113 
114```js
115function afterAllResolved(lockfile, context) {
116  // Log all resolved packages
117  context.log(`Resolved ${Object.keys(lockfile.packages || {}).length} packages`)
118  
119  // Modify lockfile if needed
120  return lockfile
121}
122```
123 
124## Context Object
125 
126The `context` object provides utilities:
127 
128```js
129function readPackage(pkg, context) {
130  // Log messages
131  context.log('Processing package...')
132  
133  return pkg
134}
135```
136 
137## Use with TypeScript
138 
139For type hints, use JSDoc:
140 
141```js
142// .pnpmfile.cjs
143 
144/**
145 * @param {import('type-fest').PackageJson} pkg
146 * @param {{ log: (msg: string) => void }} context
147 * @returns {import('type-fest').PackageJson}
148 */
149function readPackage(pkg, context) {
150  return pkg
151}
152 
153module.exports = {
154  hooks: {
155    readPackage
156  }
157}
158```
159 
160## Common Patterns
161 
162### Conditional by Package Name
163 
164```js
165function readPackage(pkg, context) {
166  switch (pkg.name) {
167    case 'package-a':
168      pkg.dependencies.foo = '^2.0.0'
169      break
170    case 'package-b':
171      delete pkg.optionalDependencies.bar
172      break
173  }
174  return pkg
175}
176```
177 
178### Apply to All Packages
179 
180```js
181function readPackage(pkg, context) {
182  // Remove all optional fsevents
183  if (pkg.optionalDependencies) {
184    delete pkg.optionalDependencies.fsevents
185  }
186  return pkg
187}
188```
189 
190### Debug Resolution
191 
192```js
193function readPackage(pkg, context) {
194  if (process.env.DEBUG_PNPM) {
195    context.log(`${pkg.name}@${pkg.version}`)
196    context.log(`  deps: ${Object.keys(pkg.dependencies || {}).join(', ')}`)
197  }
198  return pkg
199}
200```
201 
202## Hooks vs Overrides
203 
204| Feature | Hooks (.pnpmfile.cjs) | Overrides |
205|---------|----------------------|-----------|
206| Complexity | Can use JavaScript logic | Declarative only |
207| Scope | Any package metadata | Version only |
208| Use case | Complex fixes, conditional logic | Simple version pins |
209 
210**Prefer overrides** for simple version fixes. **Use hooks** when you need:
211- Conditional logic
212- Non-version modifications (exports, peer deps)
213- Logging/debugging
214 
215## Troubleshooting
216 
217### Hook not running
218 
2191. Ensure file is named `.pnpmfile.cjs` (not `.js`)
2202. Check file is at workspace root
2213. Run `pnpm install` to trigger hooks
222 
223### Debug hooks
224 
225```bash
226# See hook logs
227pnpm install --reporter=append-only
228```
229 
230<!-- 
231Source references:
232- https://pnpm.io/pnpmfile
233-->
234