moeka-project/.agents/skills/pnpm/references/features-patches.md

name, description

name	description
pnpm-patches	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 express@4.18.2

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...

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

patches/
└── express@4.18.2.patch

patchedDependencies:
  express@4.18.2: patches/express@4.18.2.patch

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 express@4.18.2

# After editing
pnpm patch-commit <path>

Remove a Patch

pnpm patch-remove <pkg>@<version>

# Example  
pnpm patch-remove express@4.18.2

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:
  express@4.18.2: patches/express@4.18.2.patch
  lodash@4.17.21: patches/lodash@4.17.21.patch
  '@types/node@20.10.0': patches/@types__node@20.10.0.patch

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:

   # In patches/README.md
   ## express@4.18.2.patch
   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 express@4.18.2
pnpm patch express@4.18.2
# 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