bun patch

Persistently patch node_modules packages in a git-friendly way

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
• .patch files can be committed to your repository and reused 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, patched packages are committed to the Global Cache and shared across projects where possible

Step 1. Prepare the package for patching

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

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

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 · 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 · default: "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 · number · default: "48"

Maximum number of concurrent network requests (default 48)

Performance & Resource

--concurrent-scripts · number · default: "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