bun patch

bun patch lets you persistently patch node_modules in a maintainable, git-friendly way.

Sometimes, you need to make a small change to a package in node_modules/ to fix a bug or add a feature. bun patch makes it easy to do this without vendoring the entire package and reuse the patch across multiple installs, multiple projects, and multiple machines.

Features:

Generates .patch files applied to dependencies in node_modules on install
.patch files can be committed to your repository, reused across multiple installs, projects, and machines
"patchedDependencies" in package.json keeps track of patched packages
bun patch lets you patch 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, patched packages are committed to the Global Cache and shared across projects where possible

Step 1. Prepare the package for patching

To get started, use bun patch <pkg> to prepare the package for patching:

terminal

# 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

Don't forget to call bun patch <pkg>! This ensures the package folder in node_modules/ contains a fresh copy of the package with no symlinks/hardlinks to Bun's cache.

If you forget to do this, 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 the <pkg> in node_modules/ directly, while preserving the integrity of Bun's Global Cache. This 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, run bun patch --commit <path or pkg>.

Bun will generate a patch file in patches/, update your package.json and lockfile, and Bun will start using the patched package:

terminal

# 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

terminal

$ 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 in the project's package.json (dependency scripts are never run)

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

booleandefault: 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

stringdefault: clonefile

Platform-specific optimizations for installing dependencies. Possible values: clonefile (default), hardlink, symlink, copyfile

--linker

string

Linker strategy (one of isolated or hoisted)

--dry-run

boolean

Don't install anything

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

numberdefault: 48

Maximum number of concurrent network requests (default 48)

Performance & Resource

--concurrent-scripts

numberdefault: 5

Maximum number of concurrent jobs for lifecycle scripts (default 5)

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

Only show tarball name when packing

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

On this page