1---
2name: pnpm-patches
3description: Patch third-party packages directly with customized fixes
4---
5 
6# pnpm Patches
7 
8pnpm's patching feature lets you modify third-party packages directly. Useful for applying fixes before upstream releases or customizing package behavior.
9 
10## Creating a Patch
11 
12### Step 1: Initialize Patch
13 
14```bash
15pnpm patch <pkg>@<version>
16 
17# Example
18pnpm patch [email protected]
19```
20 
21This creates a temporary directory with the package source and outputs the path:
22 
23```
24You can now edit the following folder: /tmp/abc123...
25```
26 
27### Step 2: Edit Files
28 
29Navigate to the temporary directory and make your changes:
30 
31```bash
32cd /tmp/abc123...
33# Edit files as needed
34```
35 
36### Step 3: Commit Patch
37 
38```bash
39pnpm patch-commit <path-from-step-1>
40 
41# Example
42pnpm patch-commit /tmp/abc123...
43```
44 
45This creates a `.patch` file in `patches/` and updates `package.json`:
46 
47```
48patches/
49└── [email protected]
50```
51 
52```json
53{
54  "pnpm": {
55    "patchedDependencies": {
56      "[email protected]": "patches/[email protected]"
57    }
58  }
59}
60```
61 
62## Patch File Format
63 
64Patches use standard unified diff format:
65 
66```diff
67diff --git a/lib/router/index.js b/lib/router/index.js
68index abc123..def456 100644
69--- a/lib/router/index.js
70+++ b/lib/router/index.js
71@@ -100,6 +100,7 @@ function createRouter() {
72   // Original code
73-  const timeout = 30000;
74+  const timeout = 60000; // Extended timeout
75   return router;
76 }
77```
78 
79## Managing Patches
80 
81### List Patched Packages
82 
83```bash
84pnpm list --depth=0
85# Shows (patched) marker for patched packages
86```
87 
88### Update a Patch
89 
90```bash
91# Edit existing patch
92pnpm patch [email protected]
93 
94# After editing
95pnpm patch-commit <path>
96```
97 
98### Remove a Patch
99 
100```bash
101pnpm patch-remove <pkg>@<version>
102 
103# Example  
104pnpm patch-remove [email protected]
105```
106 
107Or manually:
1081. Delete the patch file from `patches/`
1092. Remove entry from `patchedDependencies` in `package.json`
1103. Run `pnpm install`
111 
112## Patch Configuration
113 
114### Custom Patches Directory
115 
116```json
117{
118  "pnpm": {
119    "patchedDependencies": {
120      "[email protected]": "custom-patches/my-express-fix.patch"
121    }
122  }
123}
124```
125 
126### Multiple Packages
127 
128```json
129{
130  "pnpm": {
131    "patchedDependencies": {
132      "[email protected]": "patches/[email protected]",
133      "[email protected]": "patches/[email protected]",
134      "@types/[email protected]": "patches/@[email protected]"
135    }
136  }
137}
138```
139 
140## Workspaces
141 
142Patches are shared across the workspace. Define in the root `package.json`:
143 
144```json
145// Root package.json
146{
147  "pnpm": {
148    "patchedDependencies": {
149      "[email protected]": "patches/[email protected]"
150    }
151  }
152}
153```
154 
155All workspace packages using `[email protected]` will have the patch applied.
156 
157## Best Practices
158 
1591. **Version specificity**: Patches are tied to exact versions. Update patches when upgrading dependencies.
160 
1612. **Document patches**: Add comments explaining why the patch exists:
162   ```bash
163   # In patches/README.md
164   ## [email protected]
165   Fixes timeout issue. PR pending: https://github.com/expressjs/express/pull/1234
166   ```
167 
1683. **Minimize patches**: Keep patches small and focused. Large patches are hard to maintain.
169 
1704. **Track upstream**: Note upstream issues/PRs so you can remove patches when fixed.
171 
1725. **Test patches**: Ensure patched code works correctly in your use case.
173 
174## Troubleshooting
175 
176### Patch fails to apply
177 
178```
179ERR_PNPM_PATCH_FAILED  Cannot apply patch
180```
181 
182The package version changed. Recreate the patch:
183```bash
184pnpm patch-remove [email protected]
185pnpm patch [email protected]
186# Reapply changes
187pnpm patch-commit <path>
188```
189 
190### Patch not applied
191 
192Ensure:
1931. Version in `patchedDependencies` matches installed version exactly
1942. Run `pnpm install` after adding patch configuration
195 
196<!-- 
197Source references:
198- https://pnpm.io/cli/patch
199- https://pnpm.io/cli/patch-commit
200- https://pnpm.io/package_json#pnpmpatcheddependencies
201-->
202