🤖 I have created a release *beep* *boop*
---


##
[11.3.0](v11.2.0...v11.3.0)
(2026-06-22)
### Features
*
[`ec0f6c4`](ec0f6c4)
[#294](#294) exclude root
`.npm-extension.mjs`/`.cjs` from package tarballs (#294)
(@manzoorwanijk)
### Chores
*
[`d5ab08c`](d5ab08c)
[#293](#293) bump
@npmcli/template-oss from 5.1.0 to 5.1.1 (#293) (@dependabot[bot],
@npm-cli-bot)

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

…irs (#9586)

Implements the accepted RFC
[npm/rfcs#903](npm/rfcs#903): a root-owned
`.npm-extension.mjs` / `.npm-extension.cjs` file exporting
`transformManifest(pkg, context)` that imperatively repairs third-party
dependency manifests **before** Arborist finalizes the ideal tree. It is
the imperative counterpart to [`packageExtensions`
(#9496)](#9496) and operates in the same
pre-resolution phase, running **before** `packageExtensions`.

```js
// .npm-extension.mjs
export function transformManifest(pkg, context) {
  if (pkg.name === "foo" && pkg.version.startsWith("1.")) {
    pkg.dependencies = { ...pkg.dependencies, bar: "^2.0.0" };
    context.log("added bar to foo@1");
  }
  return pkg;
}
```

## Why

`packageExtensions` is declarative JSON: it cannot carry comments or
issue links, repeats itself across many packages, is add-only, and lives
in `package.json` (so public packages cannot publish while it is
present). `.npm-extension` covers the gap for advanced projects that
need conditional repairs, deletion, range rewrites, repeated rules
expressed as code, stale-repair guards, and a policy location outside
the published manifest.

## What it does

- **Discovery** — one root `.npm-extension.mjs` or `.npm-extension.cjs`
(both present is an error). The `extension-file` config overrides
discovery with a project-local path that must resolve inside the project
root and use `.mjs`/`.cjs`.
- **`transformManifest(pkg, context)`** — receives a deeply isolated
copy of the normalized manifest; `context` exposes `log`, `root`, and
`extensionPoint`. Must return a manifest synchronously;
`null`/primitive/array/promise returns and throws fail the install with
a `.npm-extension`-named error.
- **Allowlist** — only `dependencies`, `optionalDependencies`,
`peerDependencies`, and `peerDependenciesMeta` may change (add, replace,
or delete). Any other changed field (`scripts`, `bin`, …) is rejected.
pacote's cached manifest is never mutated.
- **Caching** — runs at most once per resolved package identity
(integrity, else resolved source + name@version); the entry file is
hash-keyed so a changed file is reloaded rather than served stale from
the module cache.
- **Lockfile** — the root entry records `npmExtensionHash` (a
format-tagged digest of the file bytes); affected entries record minimal
`npmExtensionApplied` provenance. Extension state reuses the existing
`lockfileVersion: 4` threshold.
- **Re-resolution** — changing or removing the file re-resolves the
affected packages on the next `npm install`, reverting transforms that
no longer apply.
- **`npm ci`** — never imports or executes the file; it validates the
recorded hash and reifies the locked graph (which already carries the
extension-influenced edges).
- **Configs** — `ignore-extension` disables import/execution;
`ignore-scripts` implies it; `extension-file` is honored only from
project config or the command line, never from user/global/builtin
sources.
- **Workspaces** — a `.npm-extension` file in a non-root workspace is
ignored with a warning; only the workspace root's file is honored.
- **Visibility** — `npm explain` annotates extension-changed edges and
`npm ls` (human + `--json`) surfaces the provenance.
- **Publish** — companion change in `npm-packlist` force-excludes root
`.npm-extension.{mjs,cjs}` from package tarballs.

## Companion change

Requires
[npm/npm-packlist#294](npm/npm-packlist#294) to
exclude root `.npm-extension.{mjs,cjs}` from tarballs. `pacote`/CLI will
pick this up via a version bump once that publishes.

## Notes / out of scope for this PR

One item is deferred for a genuine structural reason the RFC itself
flags:

- **Local `file:`/`link:`/directory sources.** `transformManifest`
applies to fetched manifests (registry, git, remote tarball, `file:`
tarballs) and is re-derived on the installed tree across all install
strategies including `install-strategy=linked`. It is **not yet**
applied to local sources that create `Link` nodes directly and bypass
the fetch phase — the RFC flags this as net-new wiring ("npm must add an
analogous pre-edge-read transform path for the `Link` target").
Follow-up.

## References

Implements npm/rfcs#903
Builds on #9496
Companion: npm/npm-packlist#294