Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 36 ยท Lockfiles and Security

Overrides and Resolutions

Force a specific version of a transitive dependency with npm overrides, Yarn resolutions and pnpm overrides. Learn the syntax, scoping, risks and when to remove them.

Sometimes the package you need to change is not yours and not even a direct dependency. A library three levels down has a vulnerability, a bug, or a version that breaks on your Node release, and its parent has not published a fix. You cannot edit node_modules (the next install erases it). The supported way to take control is an override: a rule in your root package.json that says "whenever anything asks for this package, use this version".

The three managers spell it differently: npm has overrides, Yarn has resolutions, and pnpm has pnpm.overrides (or overrides in pnpm-workspace.yaml). Examples in code blocks are read-only; the runnable examples implement the rule logic in plain Node.js.

The problem in a picture

flowchart TD
  A["your app"] --> B["web-framework 3.1.0"]
  A --> C["upload-tool 1.4.0"]
  B --> D["parser ^2.0.0 (2.0.1, vulnerable)"]
  C --> E["parser ^2.0.0 (same copy)"]
  A -.->|"override: parser 2.0.5"| D

The override applies to every request for parser, no matter how deep.

The syntax

npm: overrides

JSON
{
  "overrides": {
    "semver": "7.6.3",
    "express": {
      "qs": "6.13.0"
    },
    "ws@^8": "8.18.0"
  }
}
  • "semver": "7.6.3" replaces every semver in the tree.
  • "express": { "qs": ... } replaces qs only below express (a scoped override).
  • "ws@^8" applies only when the requested range is ^8.
  • A value of "$semver" means "use the same version my root dependencies use", which keeps one source of truth.

Yarn: resolutions

JSON
{
  "resolutions": {
    "semver": "7.6.3",
    "express/qs": "6.13.0",
    "**/ws": "8.18.0"
  }
}

Yarn paths use slashes. **/name matches the package anywhere. Yarn Berry also supports patch protocols to change a package's code (resolutions pointing to patch: entries), and the dedicated yarn patch command.

pnpm: overrides

JSON
{
  "pnpm": {
    "overrides": {
      "semver": "7.6.3",
      "express>qs": "6.13.0",
      "ws@<8.17.1": ">=8.17.1"
    }
  }
}

pnpm uses > for "below" and supports selectors with ranges on the left. A rule like "ws@<8.17.1": ">=8.17.1" says: any request that would resolve below the fixed version gets upgraded. pnpm audit --fix writes rules like this for you.

Rule matching you can test

Here is a stand-in that applies npm-style override rules to a dependency graph and prints which version each package ends up with. It supports a global rule, a scoped rule (under a parent) and a rule restricted to a requested range.

Node.js Stand-in: apply override rules to a dependency graph

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.

Notice that upload-tool still gets the original qs: the scoped rule applied only below web-framework.

What overrides cannot do

  • They apply from the root project only. If you publish a library, your consumers do not inherit your overrides, so they are a tool for applications and monorepo roots, not for libraries. (In a workspace, put them in the root manifest.)
  • They do not change what a package expects. Forcing parser 3.x into a framework written for 2.x can break it at run time, and nothing warns you. Test after each override.
  • They bypass the resolver's safety. A peer dependency conflict reported by npm may disappear after you override, but the conflict still exists in reality.

Keep overrides honest

Overrides are technical debt with a timestamp. Make them easy to retire:

  1. Comment them (JSON has no comments, so use a neighbouring "//" key or a README note): why, the advisory or issue URL, and the condition for removal.
  2. Prefer the narrowest rule that works (scoped and range-limited).
  3. Review them regularly. After upgrading the parent, delete the override and re-install. If nothing breaks and the audit is clean, you are done.
  4. Prefer a range like >=2.0.5 <3 over an exact pin when the fix should keep flowing in.

This stand-in checks whether each override is still needed, which is exactly what a review would do:

Node.js Stand-in: find overrides that are no longer needed

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.

A quick workflow

  1. npm audit shows parser <2.0.5 via web-framework > parser.
  2. Check whether web-framework has a newer release. If yes, upgrade it and stop.
  3. If not, add a scoped override, run npm install, and confirm with npm ls parser (Yarn: yarn why parser, pnpm: pnpm why parser).
  4. Run the test suite, re-run the audit, commit package.json and the lockfile together.
  5. Open an issue upstream and note its URL beside the override.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which field forces a dependency version in Yarn?

    Yarn uses resolutions. npm uses overrides, and pnpm uses pnpm.overrides.
  2. 2. You publish a library with an overrides block. What happens for people who install it?

    Overrides are read from the root manifest of the project doing the install, so they do not propagate through published packages.
  3. 3. What does the npm rule { "express": { "qs": "6.13.0" } } do?

    A nested object scopes the override to that parent's subtree.
  4. 4. Why should overrides be reviewed regularly?

    Overrides are workarounds. Keeping stale ones can pin an old version or hide incompatibilities.

Summary

  • Overrides (npm), resolutions (Yarn) and pnpm.overrides force a version of a transitive dependency.
  • Scope rules to a parent or a requested range whenever possible.
  • They work only from the root and do not travel with published packages.
  • Test after overriding: the parent may not support the forced version.
  • Document why, link the issue, and delete the override when the parent catches up.

Next: Monorepo Basics and Workspace Layout