Skip to content
Tutorials Center
My learning

Topics

Lesson 14 of 39 ยท Package Manager and Scripts

Overrides, Patches and Registries

Fix dependency problems in Bun - force versions with overrides, patch a package with bun patch, configure private registries and scopes in bunfig.toml or .npmrc, and publish with bun publish.

Sooner or later a dependency causes trouble. A transitive package pulls in a vulnerable version, a library has a bug that its maintainer has not fixed, or your company hosts packages on a private server. Bun has built-in answers for each: overrides change which version is chosen anywhere in the tree, patches change the code of an installed package in a way that survives reinstalls, and registry settings point Bun at other package servers. This lesson explains all three and finishes with publishing your own package.

Overrides: force a version

Suppose your app depends on A, and A depends on [email protected], which has a known problem. You cannot edit A, but you can tell Bun to use a newer lodash everywhere:

JSON
{
  "dependencies": { "A": "^2.0.0" },
  "overrides": {
    "lodash": "4.17.21"
  }
}

After bun install, every package that asks for lodash, directly or indirectly, gets 4.17.21. Bun also understands the Yarn spelling resolutions for the same purpose, which helps when migrating:

JSON
{ "resolutions": { "lodash": "4.17.21" } }

You can scope an override to a dependency of a specific parent, or point it at a different source:

JSON
{
  "overrides": {
    "lodash": "4.17.21",
    "left-pad": "npm:@scope/[email protected]",
    "some-tool": "github:you/some-tool#fix-branch"
  }
}

Use overrides sparingly and leave a note in your commit message or README saying why, and when it can be removed. Forced versions can break the package that asked for the old one, so run your tests afterwards. bun why lodash shows who depended on it.

The idea behind an override is a lookup applied during resolution. This stand-in applies an overrides table to a dependency tree and shows which versions end up requested:

Node.js Stand-in: applying overrides while resolving (Node 24)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Patches: edit a dependency safely

Editing files inside node_modules works until the next install wipes them. bun patch records your edit as a patch file that Bun re-applies after every install.

The workflow:

Terminal
bun patch express@4.21.0        # prepare the package for editing
# open node_modules/express/ and change the code you need to fix
bun patch --commit node_modules/express

The first command copies the package to a state where you can edit it in node_modules. After you commit, Bun creates a file such as patches/[email protected] (a unified diff) and records it in package.json:

JSON
{
  "patchedDependencies": {
    "[email protected]": "patches/[email protected]"
  }
}

Commit both the patch and the package.json change. Every developer and CI job that runs bun install receives the patched copy. When the package is upgraded to a version that fixes the problem, delete the entry and the patch file.

Patches are tied to an exact version. If you update express, rename or regenerate the patch and check that it still applies; a patch that no longer matches makes the install fail loudly rather than silently skipping.

Good uses for patches: a one-line bug fix awaiting an upstream release, adding a missing export, removing a noisy console.log. Bad uses: big rewrites (fork the package instead).

Registries

By default Bun fetches from the public npm registry at https://registry.npmjs.org/. Companies often use a private registry (Verdaccio, GitHub Packages, Artifactory, a cloud provider's registry) for internal packages or as a caching proxy.

Set a default registry in bunfig.toml:

TOML
[install]
registry = "https://registry.example.com/"

Or provide credentials with a token, reading it from an environment variable so it is not committed:

TOML
[install]
registry = { url = "https://registry.example.com/", token = "$NPM_TOKEN" }

Scoped registries

Often only your own scope (@acme/...) lives on the private server and everything else comes from npm:

TOML
[install.scopes]
"@acme" = { token = "$ACME_TOKEN", url = "https://npm.pkg.example.com/" }
"@other" = "https://registry.example.com/"

Now bun add @acme/ui is fetched from the private URL with the token, while bun add zod still comes from the default registry. The $NAME syntax expands an environment variable, which keeps secrets out of the file.

.npmrc is understood too

If you already have an .npmrc, Bun reads it, so a migrated project often works with no change:

TEXT
@acme:registry=https://npm.pkg.example.com/
//npm.pkg.example.com/:_authToken=${ACME_TOKEN}

Keep tokens in environment variables or your CI's secret store, never in files you commit.

Per-command registry

Terminal
bun install --registry=https://registry.example.com/

Handy for a one-off check against a mirror.

Publishing with bun publish

When your package is ready for others:

Terminal
bun pm pack --dry-run        # list the files that would be in the tarball
bun publish --dry-run        # simulate the whole publish
bun publish                  # upload to the registry
bun publish --access public  # scoped packages are private by default on npm
bun publish --tag beta       # publish under a dist-tag instead of latest

Before publishing, check:

  1. name and version are set and the version is new.
  2. files (or .npmignore) includes only what users need: source, built output, README, license.
  3. private is not true.
  4. Fields like main, exports and types point to files that exist in the tarball.
  5. Authentication: log in with npm login or set NPM_CONFIG_TOKEN; Bun reads the same credentials.

Packages that ship TypeScript source can set "exports": "./src/index.ts" if all consumers use Bun, but for general npm distribution build JavaScript and type declarations first. The bundler chapter shows how.

Security checks

  • bun audit compares your installed versions with a vulnerability database and lists advisories; run it in CI.
  • Review trustedDependencies (covered in the lockfile lesson) because they allow install scripts.
  • Prefer exact versions or a lockfile for GitHub dependencies, and pin to a commit.
  • Pair registry tokens with the least access needed: read-only for installs, publish rights only for release jobs.

Common mistakes

  • Overrides that are never removed, hiding a real upgrade need.
  • Patching without committing patches/, so CI installs the unpatched version.
  • Hard-coding a registry token in bunfig.toml. Use $ENV_VAR.
  • Publishing the whole repository because files was not set.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does an "overrides" entry in package.json do?

    Overrides replace the version Bun resolves for that package, even for transitive dependencies.
  2. 2. Why use bun patch instead of editing node_modules directly?

    Direct edits disappear on the next install; a committed patch file survives.
  3. 3. How do you send only the @acme scope to a private registry?

    Scopes in bunfig.toml (or .npmrc) map a scope to its own registry URL and token.
  4. 4. How should an auth token be provided in bunfig.toml?

    Using $NAME expands an environment variable, which keeps the secret out of version control.

Summary

  • overrides (or resolutions) force a version or source for a package everywhere in the tree; document why and remove them when possible.
  • bun patch plus bun patch --commit saves edits to a dependency as a patch file tied to patchedDependencies.
  • Configure registries and scopes in bunfig.toml (or .npmrc) with tokens read from environment variables.
  • bun pm pack and bun publish --dry-run let you inspect a release before bun publish.
  • Run bun audit in CI and keep install-script trust deliberate.

Next: Bun Build Basics