Pnpm

name: pnpm-patches description: Patch third-party packages directly with customized fixes

pnpm Patches

pnpm's patching feature lets you modify third-party packages directly. Useful for applying fixes before upstream releases or customizing package behavior.

Creating a Patch

Step 1: Initialize Patch

pnpm patch <pkg>@<version>

# Example
pnpm patch [email protected]

This creates a temporary directory with the package source and outputs the path:

You can now edit the following folder: /tmp/abc123...

Step 2: Edit Files

Navigate to the temporary directory and make your changes:

cd /tmp/abc123...
# Edit files as needed

Step 3: Commit Patch

pnpm patch-commit <path-from-step-1>

# Example
pnpm patch-commit /tmp/abc123...

pnpm patch extracts to node_modules/.pnpm_patches/<pkg> (or --edit-dir/-d <dir>; fails if non-empty: ERR_PNPM_PATCH_EDIT_DIR_EXISTS/ERR_PNPM_EDIT_DIR_NOT_EMPTY). Run pnpm install first (ERR_PNPM_PATCH_NO_LOCKFILE otherwise). If several versions are installed, pnpm asks which to patch and whether to apply to all (then the key is the bare package name). patch-commit accepts a path, or a package name/specifier (ERR_PNPM_AMBIGUOUS_PATCH_TARGET if several edit dirs match), and runs an install afterwards to apply the patch. To change a package's dependencies, use overrides or a hook, not a patched package.json.

This creates a .patch file in patches/ and records it in pnpm-workspace.yaml:

patches/
└── [email protected]

patchedDependencies:
  [email protected]: patches/[email protected]

patchedDependencies (like all pnpm settings) now lives in pnpm-workspace.yaml, not the package.json#pnpm field.

Patch File Format

Patches use standard unified diff format:

diff --git a/lib/router/index.js b/lib/router/index.js
index abc123..def456 100644
--- a/lib/router/index.js
+++ b/lib/router/index.js
@@ -100,6 +100,7 @@ function createRouter() {
   // Original code
-  const timeout = 30000;
+  const timeout = 60000; // Extended timeout
   return router;
 }

Managing Patches

List Patched Packages

pnpm list --depth=0
# Shows (patched) marker for patched packages

Update a Patch

# Edit existing patch
pnpm patch [email protected]

# After editing
pnpm patch-commit <path>

Remove a Patch

pnpm patch-remove <pkg>@<version>

# Example  
pnpm patch-remove [email protected]

patch-remove with no args lists recorded patches and prompts. It deletes the patch files, removes the keys, and deletes an empty patches dir. Errors: ERR_PNPM_NO_PATCHES_TO_REMOVE, ERR_PNPM_PATCH_NOT_FOUND.

Or manually:

1. Delete the patch file from patches/

2. Remove the entry from patchedDependencies in pnpm-workspace.yaml

3. Run pnpm install

Patch Configuration

Multiple Packages / Workspaces

Patches are shared across the whole workspace from the root pnpm-workspace.yaml:

patchedDependencies:
  [email protected]: patches/[email protected]
  [email protected]: patches/[email protected]
  '@types/[email protected]': patches/@[email protected]

A version-less key (express:) patches every installed version. All workspace packages using a matching version get the patch.

Patches from a config dependency

Patch files can live inside a shared config dependency and be referenced by path:

configDependencies:
  my-patches: '1.0.0'
patchedDependencies:
  react: node_modules/.pnpm-config/my-patches/react.patch

allowUnusedPatches

allowUnusedPatches: true   # don't fail when a listed patch wasn't applied

ignorePatchFailures was removed in v11. A patch that fails to apply now always throws. When several patches are grouped, all errors are reported together at the end.

Best Practices

1. Version specificity: Patches are tied to exact versions. Update patches when upgrading dependencies.

2. Document patches: Add comments explaining why the patch exists:

   Copy

   # In patches/README.md
   ## [email protected]
   Fixes timeout issue. PR pending: https://github.com/expressjs/express/pull/1234

3. Minimize patches: Keep patches small and focused. Large patches are hard to maintain.

4. Track upstream: Note upstream issues/PRs so you can remove patches when fixed.

5. Test patches: Ensure patched code works correctly in your use case.

Troubleshooting

Patch fails to apply

ERR_PNPM_PATCH_FAILED  Cannot apply patch

The package version changed. Recreate the patch:

pnpm patch-remove [email protected]
pnpm patch [email protected]
# Reapply changes
pnpm patch-commit <path>

Patch not applied

Ensure:

1. Version in patchedDependencies matches installed version exactly

2. Run pnpm install after adding patch configuration

<!-- Source references: - https://pnpm.io/cli/patch - https://pnpm.io/cli/patch-commit - https://pnpm.io/config-dependencies -->