f5792c40be
Pulled ALL skills from 15 source repositories: - anthropics/skills: 16 (docs, design, MCP, testing) - obra/superpowers: 14 (TDD, debugging, agents, planning) - coreyhaines31/marketingskills: 25 (marketing, CRO, SEO, growth) - better-auth/skills: 5 (auth patterns) - vercel-labs/agent-skills: 5 (React, design, Vercel) - antfu/skills: 16 (Vue, Vite, Vitest, pnpm, Turborepo) - Plus 13 individual skills from various repos Mosaic Stack is not limited to coding — the Orchestrator and subagents serve coding, business, design, marketing, writing, logistics, analysis, and more. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
202 lines
3.8 KiB
Markdown
202 lines
3.8 KiB
Markdown
---
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
cd /tmp/abc123...
|
|
# Edit files as needed
|
|
```
|
|
|
|
### Step 3: Commit Patch
|
|
|
|
```bash
|
|
pnpm patch-commit <path-from-step-1>
|
|
|
|
# Example
|
|
pnpm patch-commit /tmp/abc123...
|
|
```
|
|
|
|
This creates a `.patch` file in `patches/` and updates `package.json`:
|
|
|
|
```
|
|
patches/
|
|
└── express@4.18.2.patch
|
|
```
|
|
|
|
```json
|
|
{
|
|
"pnpm": {
|
|
"patchedDependencies": {
|
|
"express@4.18.2": "patches/express@4.18.2.patch"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Patch File Format
|
|
|
|
Patches use standard unified diff format:
|
|
|
|
```diff
|
|
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
|
|
|
|
```bash
|
|
pnpm list --depth=0
|
|
# Shows (patched) marker for patched packages
|
|
```
|
|
|
|
### Update a Patch
|
|
|
|
```bash
|
|
# Edit existing patch
|
|
pnpm patch express@4.18.2
|
|
|
|
# After editing
|
|
pnpm patch-commit <path>
|
|
```
|
|
|
|
### Remove a Patch
|
|
|
|
```bash
|
|
pnpm patch-remove <pkg>@<version>
|
|
|
|
# Example
|
|
pnpm patch-remove express@4.18.2
|
|
```
|
|
|
|
Or manually:
|
|
1. Delete the patch file from `patches/`
|
|
2. Remove entry from `patchedDependencies` in `package.json`
|
|
3. Run `pnpm install`
|
|
|
|
## Patch Configuration
|
|
|
|
### Custom Patches Directory
|
|
|
|
```json
|
|
{
|
|
"pnpm": {
|
|
"patchedDependencies": {
|
|
"express@4.18.2": "custom-patches/my-express-fix.patch"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Multiple Packages
|
|
|
|
```json
|
|
{
|
|
"pnpm": {
|
|
"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"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Workspaces
|
|
|
|
Patches are shared across the workspace. Define in the root `package.json`:
|
|
|
|
```json
|
|
// Root package.json
|
|
{
|
|
"pnpm": {
|
|
"patchedDependencies": {
|
|
"express@4.18.2": "patches/express@4.18.2.patch"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
All workspace packages using `express@4.18.2` will have the patch applied.
|
|
|
|
## 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:
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
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
|
|
|
|
<!--
|
|
Source references:
|
|
- https://pnpm.io/cli/patch
|
|
- https://pnpm.io/cli/patch-commit
|
|
- https://pnpm.io/package_json#pnpmpatcheddependencies
|
|
-->
|