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 .patchfiles can be committed to your repository and reused 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, patched packages are committed to the Global Cache and shared across projects where possible
Step 1. Prepare the package for patching
Usebun patch <pkg> to prepare the package for patching:
terminal
Don’t skip
bun patch <pkg>. 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/ and diffing it 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
boolean
Install a package containing modifications in
dirstring
The directory to put the patch file in (only if —commit is used)
Dependency Management
boolean
Don’t install devDependencies. Alias:
-pboolean
Skip lifecycle scripts in the project’s
package.json (dependency scripts are never run)boolean
Add to
trustedDependencies in the project’s package.json and install the package(s)boolean
Install globally. Alias:
-gstring
Exclude
dev, optional, or peer dependencies from installProject Files & Lockfiles
boolean
Write a
yarn.lock file (yarn v1). Alias: -yboolean
Don’t update
package.json or save a lockfileboolean
default:"true"
Save to
package.json (true by default)boolean
Disallow changes to lockfile
boolean
Save a text-based lockfile
boolean
Generate a lockfile without installing dependencies
Installation Control
string
default:"clonefile"
Platform-specific optimizations for installing dependencies. Possible values:
clonefile (default),
hardlink, symlink, copyfilestring
Linker strategy (one of
isolated or hoisted)boolean
Don’t install anything
boolean
Always request the latest versions from the registry & reinstall all dependencies. Alias:
-fboolean
Skip verifying integrity of newly downloaded packages
Network & Registry
string
Provide a Certificate Authority signing certificate
string
Same as
—ca, but as a file path to the certificatestring
Use a specific registry by default, overriding
.npmrc, bunfig.toml, and environment
variablesnumber
default:"48"
Maximum number of concurrent network requests (default 48)
Performance & Resource
number
Maximum number of concurrent jobs for lifecycle scripts (default: 2x CPU cores)
Caching
string
Store & load cached data from a specific directory path
boolean
Ignore manifest cache entirely
Output & Logging
boolean
Don’t log anything
boolean
Only show tarball name when packing
boolean
Excessively verbose logging
boolean
Disable the progress bar
boolean
Don’t print a summary
Platform Targeting
string
Override CPU architecture for optional dependencies (e.g.,
x64, arm64, * for
all)string
Override operating system for optional dependencies (e.g.,
linux, darwin, * for
all)Global Configuration & Context
string
Specify path to config file (
bunfig.toml). Alias: -cstring
Set a specific current working directory
Help
boolean
Print this help menu. Alias:
-h