Overrides & Resolutions

Force specific versions of transitive dependencies using npm overrides or Yarn resolutions.

Bun supports npm’s "overrides" and Yarn’s "resolutions" in package.json. These let you pin the version of a metadependency — a dependency of one of your dependencies — regardless of what version is requested by the package that depends on it.

When to use overrides

Consider a project with one dependency, foo, which depends on bar:

{
  "name": "my-app",
  "dependencies": {
    "foo": "^2.0.0"
  }
}

After bun install, the resolved tree might be:

node_modules
├── foo@2.1.0
└── bar@4.5.6

If bar@4.5.6 has a security vulnerability and the fix is in bar@4.4.2, you can force a specific version of bar across the entire dependency tree using overrides.

npm overrides

Add an "overrides" field to package.json:

{
  "name": "my-app",
  "dependencies": {
    "foo": "^2.0.0"
  },
  "overrides": {
    "bar": "~4.4.0"
  }
}

Bun defers to the specified version range when resolving bar, whether it appears as a direct dependency or as a transitive dependency anywhere in the tree.

Bun currently supports only top-level "overrides". Nested overrides (scoping an override to a specific dependency path) are not supported.

Yarn resolutions

Yarn uses "resolutions" instead of "overrides". Bun supports this field to ease migration from Yarn.

{
  "name": "my-app",
  "dependencies": {
    "foo": "^2.0.0"
  },
  "resolutions": {
    "bar": "~4.4.0"
  }
}

As with "overrides", nested resolutions are not currently supported.

Forcing a direct dependency version

Overrides also work on your direct dependencies. This is useful when you want to lock a dependency to a specific patch version:

{
  "dependencies": {
    "react": "^18.0.0"
  },
  "overrides": {
    "react": "18.2.0"
  }
}

Patching packages

To apply local code modifications to an installed package, use bun patch:

bun patch lodash

This opens the package source in your editor. After making changes, finalize the patch:

bun patch --commit node_modules/lodash

The patch is stored in a patches/ directory and recorded in package.json under patchedDependencies. Bun automatically applies the patch on every install.