patch: core behavior

9 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

bun patch basic purpose and workflow

bun patch persistently patches packages in node_modules in a maintainable, git-friendly way. It generates .patch files that Bun applies to dependencies on install, and .patch files can be committed to the repository and reused across installs, projects, and machines.

bun patch preserves Global Cache and disk space

When patching packages, Bun preserves the integrity of Bun's Global Cache by committing patched packages to the cache and sharing them across projects where possible. This preserves disk space and keeps bun install fast.

patchedDependencies tracking in package.json

Patched dependencies are tracked in package.json under a 'patchedDependencies' field, which keeps a record of which packages have been patched.

bun patch step 1: prepare package syntax

To prepare a package for patching, use 'bun patch <pkg>' where <pkg> can be a package name (bun patch react), a package name with version (bun patch react@17.0.2), or the path to the package (bun patch node_modules/react).

bun patch: always run prepare first

Always run 'bun patch <pkg>' first before editing. It ensures the package folder in node_modules contains a fresh copy of the package with no symlinks or hardlinks to Bun's cache. Skipping this step risks editing the package globally in the cache.

bun patch: how it protects the cache

bun patch works by recreating an unlinked clone of the package in node_modules. This makes it safe to edit the package directly while preserving the integrity of Bun's Global Cache.

bun patch --commit step 3: commit changes syntax

Once changes are made, run 'bun patch --commit <path or pkg>' to commit the patch. The path can be 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). Bun generates a patch file in patches/, updates package.json and the lockfile, and starts using the patched package.

bun patch --commit with --patches-dir flag

Use 'bun patch --commit react --patches-dir=mypatches' to choose the directory where patch files are stored instead of the default patches/ directory.

bun patch-commit alias for compatibility

The command 'bun patch-commit' is available as an alias for 'bun patch --commit' for compatibility with pnpm.

Give your agent this brain