bun patch persistently patches packages in node_modules in a maintainable, git-friendly way.
Sometimes you need a small change to a package in node_modules/ to fix a bug or add a feature. bun patch lets you do this without vendoring the entire package.
Features:
- Generates
.patchfiles that Bun applies to dependencies innode_moduleson install - You can commit
.patchfiles to your repository and reuse them across installs, projects, and machines "patchedDependencies"inpackage.jsonkeeps track of patched packages- Patches packages in
node_modules/while preserving the integrity of Bun’s Global Cache - Test your changes locally before committing them with
bun patch --commit <pkg> - To preserve disk space and keep
bun installfast, Bun commits patched packages to the Global Cache and shares them across projects where possible
Step 1. Prepare the package for patching
Usebun patch <pkg> to prepare the package for patching:
terminal
Always run
bun patch <pkg> first. It ensures the package folder in node_modules/ contains a fresh copy of the package with no symlinks or hardlinks to Bun’s cache.If you skip it, you might end up editing the package globally in the cache.Step 2. Test your changes locally
bun patch <pkg> makes it safe to edit <pkg> in node_modules/ directly, while preserving the integrity of Bun’s Global Cache. It works by re-creating an unlinked clone of the package in node_modules/. bun patch --commit <pkg> then diffs that clone against the original package in the Global Cache.
Step 3. Commit your changes
Once you’re happy with your changes, runbun patch --commit <path or pkg>.
Bun generates a patch file in patches/, updates your package.json and lockfile, and starts using the patched package:
terminal
CLI Usage
Patch Generation
Dependency Management
Skip lifecycle scripts for all packages, including the project’s
package.json and trusted dependenciesProject Files & Lockfiles
Installation Control
Platform-specific optimizations for installing dependencies. Possible values:
clonefile (default on
macOS), hardlink (default on Linux and Windows), symlink, copyfile