With npm, why does an `overrides` entry in a published library's package.json do nothing for the apps that install it, and how does an app force a patched transitive version instead?
answer
- who owns the tree
- root package.json only
- ignored in installed dependencies
- nested keys scope the override
- $name matches a direct dependency
basics
~10 snpm reads overrides only from the root project's package.json; entries in installed dependencies, workspaces included, are ignored. The app adds its own override, such as "xml-tiny-parser": "^2.8.4", in its root manifest and reinstalls.
solid answer
~40 s`overrides` rewrites what dependency edges resolve to, and npm considers it **only in the root `package.json`** of the project being installed. When `@fleetline/charts` is installed into the dispatch dashboard, the dashboard is the root, so the library's `overrides` are ignored; they only ever applied in the library's own repository, which is why its CI looked fixed. The dashboard adds the entry itself: `"xml-tiny-parser": "^2.8.4"` for every copy, or nested under `"svg-writer"` to touch only that path. If the dashboard also depends on the parser directly, the override must use the same spec or a `$xml-tiny-parser` reference, or npm throws `EOVERRIDE`. A library that must control the version for its consumers changes its own dependencies: a fixed or forked upstream, or `bundleDependencies`.
code
json · 11 lines{
"name": "dispatch-dashboard",
"private": true,
"dependencies": {
"@fleetline/charts": "^3.2.0",
"xml-tiny-parser": "^2.8.4"
},
"overrides": {
"xml-tiny-parser": "$xml-tiny-parser"
}
}go deeper
Recall that overrides lives in package.json and forces a version of a package your dependencies bring in.
Write the global, nested and $ reference forms, and explain the EOVERRIDE error for a direct dependency.
Explain why a library's override never reaches consumers, and choose between pinning, a fork, bundling or documenting the override for apps.
Own a policy for security overrides across many apps: who adds them, how each records its removal trigger, and how drift is reviewed.
## What `overrides` does The `overrides` field in `package.json` replaces a package somewhere in the dependency tree with another version, or another package entirely, regardless of what the packages that depend on it asked for. It is the tool for forcing a patched copy of a vulnerable transitive package, swapping in a fork, or making sure one version is used everywhere. The scenario: `@fleetline/charts` uses `svg-writer`, which depends on `xml-tiny-parser@~2.7.0`. Version 2.8.4 fixes a vulnerability, but the `svg-writer` maintainer will not release a bump. ## Why the library's override does nothing downstream npm's rule is short: **overrides are only considered in the root `package.json` of a project**. Overrides in installed dependencies, including workspaces, are not considered when npm resolves the tree. - In the library's own repository, `@fleetline/charts` *is* the root, so an override there works: its tests and CI install the patched parser. - Once the library is published and installed into the dispatch dashboard, the dashboard is the root. npm reads the dashboard's `overrides` and ignores the library's. - The result is a library team that believes the fix shipped, and consumers who still install `[email protected]`. - The same rule covers workspaces: an override in a workspace's own manifest is ignored, so in a repository with workspaces it belongs in the top-level `package.json`. - A published override does no harm, but it is dead text for every consumer, and a reviewer should ask what the library meant it to fix. The rule is deliberate: the project being installed owns its tree, and a dependency cannot reach out and rewrite versions for its consumers. npm's docs point published packages to the tools they do control: pinning their own dependencies, or `bundleDependencies`. ## How the app writes the override The dashboard's root `package.json` takes the fix. The forms, from broad to narrow: 1. **Everywhere**: `"xml-tiny-parser": "^2.8.4"`. A range enforces a minimum patched release; an exact version pins one. 2. **Only beneath one parent**: `"svg-writer": { "xml-tiny-parser": "2.8.4" }` overrides the parser only when it is a child, grandchild or deeper descendant of `svg-writer`. 3. **Only beneath one parent version**: a key such as `"[email protected]"` limits the rule to that version of the parent. 4. **A package and its child**: the object form with a `"."` key overrides the package itself as well as a dependency of it. Override values accept any specifier npm accepts for dependencies: a version, a range, a dist-tag, or a replacement such as `npm:` for a fork published under another name, or a `file:` path. ## Direct dependencies and `$` references If the dashboard *also* depends on `xml-tiny-parser` directly, npm restricts the override: you may not override a package you directly depend on unless the dependency and the override share **exactly the same spec**. An override of `"^3.0.0"` next to a direct `"^2.8.4"` throws an **`EOVERRIDE`** error. The convenient form is a **reference**: the value `"$xml-tiny-parser"` means "use whatever spec my direct dependency on `xml-tiny-parser` declares". Bumping the direct dependency then moves every transitive copy with it, and the two can never drift apart. The referenced package does not even have to be the overridden one; any direct dependency's spec can be borrowed. ## After writing it - Run `npm install` so the tree and `package-lock.json` are rebuilt with the override applied; a lockfile written before the change does not reflect it. - Confirm which version each path resolved to with `npm ls xml-tiny-parser`. - Record why the override exists and when to remove it: once `svg-writer` releases a version that accepts 2.8.4, the override is dead weight that can hide the next upgrade. ## What the library author can do instead | Option | Reaches consumers? | Trade-off | |---|---|---| | `overrides` in the library | no, root-only | works only in the library's own repository | | Bump or pin its own direct dependency | yes | only possible for packages it depends on directly | | Depend on a fixed fork of `svg-writer` via an `npm:` alias | yes | the library now maintains or tracks a fork | | `bundleDependencies` for `svg-writer` | yes | the tarball carries that subtree; consumers cannot dedupe it, and every fix needs a library release | | Document the override for consumers | only if they add it | relies on every app reading the release notes | Forcing an override is a local decision with a cost: the app now runs a combination `svg-writer` never declared. Testing the rendering path is part of the change.
- The patched parser exists only as your own fork. How does the app's override point at it?Use a replacement spec as the override value in the root manifest, for example `"xml-tiny-parser": "npm:@fleetline/[email protected]"` for a fork published under your scope; a `file:` path also works. Every matching edge then installs the fork under the original name, so `svg-writer`'s `require` still resolves.
- How would you override `xml-tiny-parser` only where `svg-writer` brings it in, leaving other copies alone?Nest it under the parent in the root manifest: `"overrides": { "svg-writer": { "xml-tiny-parser": "2.8.4" } }`. npm applies it only when the parser is a descendant of `svg-writer`; a key such as `"[email protected]"` narrows it further to one parent version.
Overrides are house rules posted by the owner of the house. A guest who arrives with a printed sheet of their own rules changes nothing about how that house is run; the library is the guest, and the root project is the house that decides.
- overrides in a published library apply to every app that installs it
- an override can contradict a direct dependency's spec freely
- a nested override changes the package everywhere in the tree
- overrides belong in .npmrc rather than package.json
- overrides only accept exact versions, never ranges