feat: packageExtensions for root-owned dependency manifest repairs (#9496)

Implements package manifest extensions per [RFC
#889](npm/rfcs#889): a root-only
`packageExtensions` field in `package.json` that applies declarative
repairs to third-party dependency manifests **before** Arborist
finalizes the ideal tree. It lets a project add missing
`dependencies`/`optionalDependencies`, add or correct
`peerDependencies`, and mark peers optional via `peerDependenciesMeta`,
without forking and republishing a package.

```json
{
  "packageExtensions": {
    "broken-package@1": {
      "dependencies": { "missing-runtime-dep": "^2.0.0" }
    },
    "typescript-plugin@4.3.0": {
      "peerDependencies": { "typescript": ">=5" },
      "peerDependenciesMeta": { "typescript": { "optional": true } }
    }
  }
}
```

## Why

`install-strategy=linked` gives installs strong package boundaries,
which is also what makes adoption hard: a package only sees what it
actually declared, so one that worked under a hoisted layout because a
dependency happened to be hoisted above it can fail. A root-level
dependency masks this under hoisting but does not make the package
available inside the isolated boundary of the importer — the repair has
to be attached to the broken package's manifest before its edges are
resolved. This is the pre-resolution complement to `overrides` (which
needs an existing edge to retarget) and to [native dependency patching
#9439](#9439) (which edits package
contents after resolution).

## The field

Each key is a package selector: a name with an optional semver range
(`foo`, `foo@1`, `@scope/foo@^2.3.0`). Selectors match a candidate's own
manifest `name`/`version` (the underlying name for aliases) and reject
dist-tag, git, file, URL, and `npm:` specs. At most one selector may
match a candidate. Honored only in the root `package.json` (the
workspace root); the field in dependencies and non-root workspaces, and
selectors matching a workspace member, are ignored with a warning —
matching the root-authority model of `overrides`.

## Merge semantics

Only the four resolution-affecting fields may be extended.

- `dependencies`/`optionalDependencies` add a missing name only;
providing a name already declared in either field is an error (use
`overrides` to change a version), which also forbids moving a name
between the two.
- `peerDependencies` shallow-merges by name, replacing an existing
range.
- `peerDependenciesMeta` merges by name then key (e.g. add `optional:
true`); every meta entry must have a corresponding `peerDependencies`
entry.
- Deletion (`null`/`false`/`"-"`) is not supported.

The extension applies to a per-tree manifest copy: the shared
pacote/cache manifest is never mutated, the installed
`node_modules/<pkg>/package.json` is not rewritten, and
`bundleDependencies` is unchanged. `overrides` still controls the final
resolution target of an extension-created edge.

## Lockfile

The root entry stores a canonical `packageExtensionsHash`, and each
affected entry stores minimal provenance (`packageExtensionsApplied`);
effective dependency metadata is recorded as usual. Extension state
forces `lockfileVersion: 4` so older npm clients abort rather than
silently dropping the repaired graph. `npm install` re-resolves affected
packages when the rule set changes; `npm ci` validates the hash,
selector conflicts, and stale provenance before trusting the locked
metadata.

## Visibility

`npm explain` appends `(added by
packageExtensions["foo@1"].dependencies.bar)` to the edge; `npm ls`
annotates the node and `npm ls --json` includes
`packageExtensionsApplied`. Publishing a non-private package containing
the field warns that it does not affect consumers.

## Notes

- `lockfileVersion: 4` is shared with native dependency patching
([#9439](#9439)) as a common "older npm
must not silently drop this" tripwire; both bump only when their own
state is present. Whichever lands second should reuse the same
`maxLockfileVersion`/bump constants rather than introduce a competing
version.
- Opt-in and additive, so it can ship in a minor release.

## References

Implements npm/rfcs#889

Author: manzoorwanijk

DEPENDENCIES.md

@@ -184,6 +184,7 @@ graph LR;
   npmcli-arborist-->proggy;
   npmcli-arborist-->semver;
   npmcli-arborist-->ssri;
+  npmcli-arborist-->validate-npm-package-name;
   npmcli-config-->ini;
   npmcli-config-->nopt;
   npmcli-config-->npmcli-eslint-config["@npmcli/eslint-config"];
@@ -579,6 +580,7 @@ graph LR;
   npmcli-arborist-->tar-stream;
   npmcli-arborist-->tcompare;
   npmcli-arborist-->treeverse;
+  npmcli-arborist-->validate-npm-package-name;
   npmcli-arborist-->walk-up-path;
   npmcli-config-->ci-info;
   npmcli-config-->ini;

docs/lib/content/configuring-npm/package-json.md

@@ -1033,6 +1033,66 @@ For example, to replace a transitive dependency with a fork:
 }
 ```
 
+### packageExtensions
+
+`packageExtensions` lets a project apply small, declarative repairs to the manifests of third-party dependencies before npm resolves the dependency tree.
+Use it to add a missing `dependencies`, `optionalDependencies`, or `peerDependencies` entry, or to correct `peerDependencies` and `peerDependenciesMeta`, while you wait for the upstream package to publish a fix.
+
+This is especially useful with [`install-strategy=linked`](/using-npm/config#install-strategy), where dependencies are fully isolated and a package only sees what it actually declared.
+A package that worked under a hoisted layout because a dependency happened to be hoisted above it can fail under `linked`; `packageExtensions` records the missing edge as explicit, reviewable, root-owned policy.
+
+`packageExtensions` complements [`overrides`](#overrides): `overrides` changes what an existing dependency edge resolves to, while `packageExtensions` adds or corrects the dependency metadata that creates the edge in the first place.
+For changing the resolved version of a dependency that is already declared, use `overrides`.
+
+Like `overrides`, `packageExtensions` is only honored in the root `package.json` of a project (the workspace root in a workspace).
+The field in installed dependencies and in non-root workspace packages is ignored.
+Because it is root-only project policy, npm refuses to publish a non-private package that contains `packageExtensions`; it remains available to private packages and unpublished local projects.
+
+Each key is a package selector: a package name with an optional semver range.
+
+```json
+{
+  "packageExtensions": {
+    "broken-package@1": {
+      "dependencies": {
+        "missing-runtime-dep": "^2.0.0"
+      }
+    },
+    "typescript-plugin@4.3.0": {
+      "peerDependencies": {
+        "typescript": ">=5"
+      },
+      "peerDependenciesMeta": {
+        "typescript": {
+          "optional": true
+        }
+      }
+    },
+    "@scope/uses-types@2": {
+      "dependencies": {
+        "@types/node": "^22.0.0"
+      }
+    }
+  }
+}
+```
+
+- `"foo"` matches all versions of `foo`.
+- `"foo@1"` matches versions satisfying `1`.
+- `"@scope/foo@^2.3.0"` matches versions satisfying `^2.3.0`.
+
+Selectors match a candidate package's own `name` and `version`. They do not accept dist-tags, git, file, directory, URL, or `npm:` alias specs. For aliases, the selector matches the underlying package name. At most one selector may match a given package; overlapping selectors that both match the same package fail the install.
+
+Only `dependencies`, `optionalDependencies`, `peerDependencies`, and `peerDependenciesMeta` may be extended. The merge rules are:
+
+- `dependencies` and `optionalDependencies` entries add a missing dependency only. Adding a name that the package already declares in either field is an error; use `overrides` to change a version.
+- `peerDependencies` entries are merged by name, replacing an existing range.
+- `peerDependenciesMeta` entries are merged by name and then by key, so you can add `optional: true` without dropping other metadata. Every `peerDependenciesMeta` entry must correspond to a `peerDependencies` entry.
+
+Deletion is not supported; a `null`, `false`, or `"-"` value is an error.
+
+`packageExtensions` does not rewrite the installed package's `package.json` on disk and does not modify `bundleDependencies`. Affected packages are recorded in `package-lock.json` and surfaced by [`npm explain`](/commands/npm-explain) and [`npm ls`](/commands/npm-ls), so each repair is easy to audit and to remove once upstream is fixed.
+
 ### engines
 
 You can specify the version of node that your stuff works on:

lib/commands/ci.js

@@ -6,6 +6,7 @@ const fs = require('node:fs/promises')
 const path = require('node:path')
 const { log, time } = require('proc-log')
 const validateLockfile = require('../utils/validate-lockfile.js')
+const { validatePackageExtensions } = require('../utils/validate-lockfile.js')
 const ArboristWorkspaceCmd = require('../arborist-cmd.js')
 const getWorkspaces = require('../utils/get-workspaces.js')
 
@@ -89,6 +90,8 @@ class CI extends ArboristWorkspaceCmd {
 
     // Verifies that the packages from the ideal tree will match the same versions that are present in the virtual tree (lock file).
     const errors = validateLockfile(virtualInventory, arb.idealTree.inventory)
+    // Verifies that the root packageExtensions state matches the lockfile and is still consistent with the locked tree.
+    errors.push(...validatePackageExtensions(virtualArb.virtualTree, arb.idealTree))
     if (errors.length) {
       throw this.usageError(
         '`npm ci` can only install packages when your package.json and package-lock.json are in sync. ' +

lib/commands/ls.js

@@ -278,6 +278,21 @@ const augmentItemWithIncludeMetadata = (node, item) => {
   return item
 }
 
+// Render a node's packageExtensions provenance as a short "field.name" list, empty when none.
+const formatPackageExtensions = (applied) => {
+  if (!applied) {
+    return ''
+  }
+  const fields = ['dependencies', 'optionalDependencies', 'peerDependencies', 'peerDependenciesMeta']
+  const parts = []
+  for (const field of fields) {
+    for (const name of applied[field] || []) {
+      parts.push(`${field}.${name}`)
+    }
+  }
+  return parts.join(', ')
+}
+
 const getHumanOutputItem = (node, { args, chalk, global, long }) => {
   const { pkgid, path } = node
   const workspacePkgId = chalk.blueBright(pkgid)
@@ -338,6 +353,11 @@ const getHumanOutputItem = (node, { args, chalk, global, long }) => {
         ? ' ' + chalk.cyan(`[patched: ${node.patched.path}]`)
         : ''
     ) +
+    (
+      formatPackageExtensions(node.packageExtensionsApplied)
+        ? ' ' + chalk.dim(`packageExtensions: ${formatPackageExtensions(node.packageExtensionsApplied)}`)
+        : ''
+    ) +
     (isGitNode(node) ? ` (${node.resolved})` : '') +
     (node.isLink ? ` -> ${relativePrefix}${targetLocation}` : '') +
     (long ? `\n${node.package.description || ''}` : '')
@@ -362,6 +382,10 @@ const getJsonOutputItem = (node, { global, long }) => {
     item.overridden = node.overridden
   }
 
+  if (node.packageExtensionsApplied) {
+    item.packageExtensionsApplied = node.packageExtensionsApplied
+  }
+
   item[_name] = node.name
 
   // special formatting for top-level package name

lib/commands/publish.js

@@ -96,6 +96,9 @@ class Publish extends BaseCommand {
     const spec = npa(args[0])
     let manifest = await this.#getManifest(spec, opts)
 
+    // packageExtensions is root-only project policy and must never be published; fail fast so dry-run reports it too
+    this.#assertNoPackageExtensions(manifest)
+
     // only run scripts for directory type publishes
     if (spec.type === 'directory' && !ignoreScripts) {
       await runScript({
@@ -122,6 +125,8 @@ class Publish extends BaseCommand {
 
     // The purpose of re-reading the manifest is in case it changed, so that we send the latest and greatest thing to the registry note that publishConfig might have changed as well!
     manifest = await this.#getManifest(spec, opts, true)
+    // re-check the authoritative manifest in case a lifecycle script introduced packageExtensions
+    this.#assertNoPackageExtensions(manifest)
     const force = this.npm.config.get('force')
     const isDefaultTag = this.npm.config.isDefault('tag') && !manifest.publishConfig?.tag
 
@@ -273,6 +278,16 @@ class Publish extends BaseCommand {
     }
   }
 
+  // packageExtensions is root-only project policy and must never reach the registry; private packages may keep it for local use
+  #assertNoPackageExtensions (manifest) {
+    if (!manifest.private && manifest.packageExtensions !== undefined) {
+      throw Object.assign(
+        new Error('packageExtensions is only honored at the project root and must not be published.'),
+        { code: 'EPACKAGEEXTENSIONS' }
+      )
+    }
+  }
+
   // if it's a directory, read it from the file system
   // otherwise, get the full metadata from whatever it is
   // XXX can't pacote read the manifest from a directory?

lib/utils/explain-dep.js

@@ -76,7 +76,7 @@ const explainDependents = ({ dependents }, depth, chalk, seen) => {
 }
 
 const explainEdge = (
-  { name, type, bundled, from, spec, rawSpec, overridden },
+  { name, type, bundled, from, spec, rawSpec, overridden, packageExtensions },
   depth, chalk, seen = new Set()
 ) => {
   let dep = type === 'workspace'
@@ -88,9 +88,14 @@ const explainEdge = (
 
   const fromMsg = ` from ${explainFrom(from, depth, chalk, seen)}`
 
+  // note an edge created by a root packageExtensions repair
+  const extMsg = packageExtensions
+    ? chalk.dim(` (added by packageExtensions["${packageExtensions.selector}"].${packageExtensions.field}.${name})`)
+    : ''
+
   return (type === 'prod' ? '' : `${colorType(type, chalk)} `) +
     (bundled ? `${colorType('bundled', chalk)} ` : '') +
-    `${dep}${fromMsg}`
+    `${dep}${fromMsg}${extMsg}`
 }
 
 const explainFrom = (from, depth, chalk, seen) => {

lib/utils/validate-lockfile.js

@@ -33,4 +33,59 @@ function validateLockfile (virtualTree, idealTree) {
   return errors
 }
 
+// validates that the root packageExtensions state matches what the lockfile recorded, and that the locked tree is still consistent with the rule set.
+// Returns an array of human-readable error strings, empty when valid.
+function validatePackageExtensions (virtualTree, idealTree) {
+  const errors = []
+  const lockHash = virtualTree.meta?.packageExtensionsHash || null
+  const idealHash = idealTree.meta?.packageExtensionsHash || null
+
+  if (idealHash !== lockHash) {
+    if (idealHash && !lockHash) {
+      errors.push('Missing: packageExtensions state from lock file')
+    } else if (!idealHash && lockHash) {
+      errors.push('Invalid: lock file records packageExtensions state but package.json has none')
+    } else {
+      errors.push('Invalid: packageExtensions in package.json do not match the lock file')
+    }
+    // once the canonical hashes diverge, the deeper per-node checks are moot
+    return errors
+  }
+
+  // the hashes match, so validate the locked tree's own consistency against the rules
+  const { PackageExtensions } = require('@npmcli/arborist')
+  const root = idealTree.target || idealTree
+  let pe
+  try {
+    pe = new PackageExtensions(root.package?.packageExtensions)
+  } catch (err) {
+    return [`Invalid: ${err.message}`]
+  }
+
+  for (const node of virtualTree.inventory.values()) {
+    if (node.isProjectRoot || node.isWorkspace) {
+      continue
+    }
+    // selectors match the underlying package identity, which is the alias target for aliased installs
+    const name = node.packageName || node.name
+    // a locked package identity must not match more than one selector
+    try {
+      pe.match(name, node.version)
+    } catch (err) {
+      errors.push(`Invalid: ${err.message}`)
+    }
+    // recorded provenance must still correspond to a selector that matches the node
+    const applied = node.packageExtensionsApplied
+    if (applied) {
+      const sel = pe.selectors.find(s => s.key === applied.selector)
+      if (!sel || !pe.wouldMatch(name, node.version)) {
+        errors.push(
+          `Invalid: stale packageExtensions provenance for ${node.name}@${node.version} (selector "${applied.selector}")`)
+      }
+    }
+  }
+  return errors
+}
+
 module.exports = validateLockfile
+module.exports.validatePackageExtensions = validatePackageExtensions

package-lock.json

@@ -16915,6 +16915,7 @@
         "semver": "^7.3.7",
         "ssri": "^14.0.0",
         "treeverse": "^3.0.0",
+        "validate-npm-package-name": "^7.0.2",
         "walk-up-path": "^4.0.0"
       },
       "bin": {
@@ -16935,6 +16936,15 @@
         "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
       }
     },
+    "workspaces/arborist/node_modules/validate-npm-package-name": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/validate-npm-package-name/-/validate-npm-package-name-7.0.2.tgz",
+      "integrity": "sha512-hVDIBwsRruT73PbK7uP5ebUt+ezEtCmzZz3F59BSr2F6OVFnJ/6h8liuvdLrQ88Xmnk6/+xGGuq+pG9WwTuy3A==",
+      "license": "ISC",
+      "engines": {
+        "node": "^20.17.0 || >=22.9.0"
+      }
+    },
     "workspaces/config": {
       "name": "@npmcli/config",
       "version": "11.0.0-pre.0",

tap-snapshots/test/lib/commands/ls.js.test.cjs

@@ -556,6 +556,12 @@ exports[`test/lib/commands/ls.js TAP ls overridden dep w/ color > should contain
 
 `
 
+exports[`test/lib/commands/ls.js TAP ls packageExtensions dep > human output annotates the extended node 1`] = `
+test-package-extensions@1.0.0 {CWD}/prefix
+\`-- foo@1.0.0 packageExtensions: dependencies.bar
+  \`-- bar@1.0.0
+`
+
 exports[`test/lib/commands/ls.js TAP ls print deduped symlinks > should output tree containing linked deps 1`] = `
 print-deduped-symlinks@1.0.0 {CWD}/prefix
 +-- a@1.0.0

tap-snapshots/test/lib/utils/explain-dep.js.test.cjs

@@ -205,6 +205,30 @@ overridden-root@1.0.0 overridden
 node_modules/overridden-root
 `
 
+exports[`test/lib/utils/explain-dep.js TAP basic packageExtensions > explain color deep 1`] = `
+bar@1.2.3
+node_modules/bar
+  bar@"^1.0.0" from foo@1.0.0
+  node_modules/foo (added by packageExtensions["foo@1"].dependencies.bar)
+`
+
+exports[`test/lib/utils/explain-dep.js TAP basic packageExtensions > explain nocolor shallow 1`] = `
+bar@1.2.3
+node_modules/bar
+  bar@"^1.0.0" from foo@1.0.0
+  node_modules/foo (added by packageExtensions["foo@1"].dependencies.bar)
+`
+
+exports[`test/lib/utils/explain-dep.js TAP basic packageExtensions > print color 1`] = `
+bar@1.2.3
+node_modules/bar
+`
+
+exports[`test/lib/utils/explain-dep.js TAP basic packageExtensions > print nocolor 1`] = `
+bar@1.2.3
+node_modules/bar
+`
+
 exports[`test/lib/utils/explain-dep.js TAP basic peer > explain color deep 1`] = `
 peer@1.0.0 peer
 node_modules/peer