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 .patch files that Bun applies to dependencies in node_modules on install
You can commit .patch files to your repository and reuse them across installs, projects, and machines
"patchedDependencies" in package.json keeps 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 install fast, Bun commits patched packages to the Global Cache and shares them across projects where possible

Step 1. Prepare the package for patching

Use bun patch <pkg> to prepare the package for patching:

# you can supply the package name
bun patch react

# ...and a precise version in case multiple versions are installed
bun patch react@17.0.2

# or the path to the package
bun patch node_modules/react

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, run bun patch --commit <path or pkg>.

Bun generates a patch file in patches/, updates your package.json and lockfile, and starts using the patched package:

# you can supply the path to the patched package
bun patch --commit node_modules/react

# ... or the package name and optionally the version
bun patch --commit react@17.0.2

# choose the directory to store the patch files
bun patch --commit react --patches-dir=mypatches

# `patch-commit` is available for compatibility with pnpm
bun patch-commit react

CLI Usage

bun patch <package>@<version>

Patch Generation

--commit boolean

Install a package containing modifications in dir

--patches-dir string

The directory to put the patch file in (only if --commit is used)

Dependency Management

--production boolean

Don't install devDependencies. Alias: -p

--ignore-scripts boolean

Skip lifecycle scripts for all packages, including the project's package.json and trusted dependencies

--trust boolean

Add to trustedDependencies in the project's package.json and install the package(s)

--global boolean

Install globally. Alias: -g

--omit string

Exclude dev, optional, or peer dependencies from install

Project Files & Lockfiles

--yarn boolean

Write a yarn.lock file (yarn v1). Alias: -y

--no-save boolean

Don't update package.json or save a lockfile

--save boolean default: true

Save to package.json (true by default)

--frozen-lockfile boolean

Disallow changes to lockfile

--save-text-lockfile boolean

Save a text-based lockfile

--lockfile-only boolean

Generate a lockfile without installing dependencies

Installation Control

--backend string

Platform-specific optimizations for installing dependencies. Possible values: clonefile (default on macOS), hardlink (default on Linux and Windows), symlink, copyfile

--linker string

Linker strategy (one of isolated or hoisted)

--minimum-release-age number

Only install packages published at least N seconds ago (security feature)

--dry-run boolean

Don't install packages, update package.json, or save a lockfile. The package is still copied into{" "} node_modules for patching, and --commit still writes the patch file

--force boolean

Always request the latest versions from the registry & reinstall all dependencies. Alias: -f

--no-verify boolean

Skip verifying integrity of newly downloaded packages

Network & Registry

--ca string

Provide a Certificate Authority signing certificate

--cafile string

Same as --ca, but as a file path to the certificate

--registry string

Use a specific registry by default, overriding .npmrc, bunfig.toml, and environment variables

--network-concurrency number default: 48

Maximum number of concurrent network requests (default 48)

Performance & Resource

--concurrent-scripts number

Maximum number of concurrent jobs for lifecycle scripts (default: 2x CPU cores)

Caching

--cache-dir string

Store & load cached data from a specific directory path

--no-cache boolean

Ignore manifest cache entirely

Output & Logging

--silent boolean

Don't log anything

--quiet boolean

Disable the progress bar

--verbose boolean

Excessively verbose logging

--no-progress boolean

Disable the progress bar

--no-summary boolean

Don't print a summary

Platform Targeting

--cpu string

Override CPU architecture for optional dependencies (e.g., x64, arm64, * for all)

--os string

Override operating system for optional dependencies (e.g., linux, darwin, * for all)

Global Configuration & Context

--config string

Specify path to config file (bunfig.toml). Alias: -c

--cwd string

Set a specific current working directory

Help

--help boolean

Print this help menu. Alias: -h