VitePress

Appearance

Patching Node Modules with Bun ​

Sometimes you may need to patch a dependency in node_modules—for example, to fix a bug or apply a temporary workaround before an upstream fix is released. Bun makes this process straightforward with its built-in patching system.

Why Patch? ​

  • Urgent bugfixes: Apply a fix before it's merged upstream.
  • Custom behavior: Add or change functionality for your use case.
  • Temporary workarounds: Unblock development while waiting for a package update.

How Bun Patching Works ​

Bun supports patching node modules using the bun add --use and bun pm patch commands. This creates a patch file that is automatically applied whenever you install dependencies.

Step-by-Step: Patching a Module ​

1. Find the Module to Patch ​

Decide which package and file you need to patch. For example, suppose you want to patch some-package in node_modules.

2. Run the Patch Command ​

sh
bun pm patch some-package

This will:

  • Copy the package to a temporary directory.
  • Open your editor to make changes.

3. Make Your Changes ​

Edit the files as needed. Save and close your editor when done.

4. Bun Creates a Patch File ​

Bun will generate a patch file (e.g., patches/some-package@1.2.3.patch) in your project. This patch will be applied automatically on future installs.

5. Commit the Patch ​

Be sure to commit the patch file to your repository so others get the same fix.

6. Verify ​

Reinstall dependencies and check that your patch is applied:

sh
bun install

Example ​

Suppose you want to patch a bug in node_modules/some-package/index.js:

sh
bun pm patch some-package
# Your editor opens. Make your changes, save, and close.
# Bun creates patches/some-package@x.y.z.patch

Notes ​

  • Patches are version-specific: If the package version changes, you may need to re-create or update the patch.
  • Keep patches minimal: Only patch what you must, and remove patches when no longer needed.
  • Upstream first: Always try to contribute your fix upstream if possible.

References ​