Is there an existing issue for this?
This is a CLI Docs Enhancement, not another kind of Docs Enhancement.
Description of Problem
The docs describe install-strategy=linked (isolated mode) as an install option for consumers, but nothing points package authors at it as a pre-publish check. Under the default flat node_modules, a package can import a dependency it never declared and still resolve it — a transitive dependency gets hoisted alongside it, and Node's resolution finds it (the classic "phantom dependency"). That undeclared dependency passes the author's own build silently, then fails for a consumer who installs the package on its own. Isolated mode only exposes a package's declared dependencies, so it surfaces these at the author's build — but the docs don't mention it as an authoring check.
Potential Solution
Add a short "For package authors" note to the install-strategy config documentation (and/or the package-creation/publishing guide). Suggested copy:
We recommend that package authors use --install-strategy=linked during development to catch undeclared ("phantom") dependencies before publishing: the isolated layout only exposes a package's declared dependencies, so an import of a package that was never added to `package.json` can fail instead of resolving by accident and shipping broken.
Placement options: inline under the install-strategy entry in the config reference, or as a tip in the "creating and publishing packages" guide, cross-linked from the config entry.
Docs URL
https://docs.npmjs.com/cli/v11/using-npm/config#install-strategy
Is there an existing issue for this?
This is a CLI Docs Enhancement, not another kind of Docs Enhancement.
Description of Problem
The docs describe
install-strategy=linked(isolated mode) as an install option for consumers, but nothing points package authors at it as a pre-publish check. Under the default flatnode_modules, a package canimporta dependency it never declared and still resolve it — a transitive dependency gets hoisted alongside it, and Node's resolution finds it (the classic "phantom dependency"). That undeclared dependency passes the author's own build silently, then fails for a consumer who installs the package on its own. Isolated mode only exposes a package's declared dependencies, so it surfaces these at the author's build — but the docs don't mention it as an authoring check.Potential Solution
Add a short "For package authors" note to the
install-strategyconfig documentation (and/or the package-creation/publishing guide). Suggested copy:Placement options: inline under the
install-strategyentry in the config reference, or as a tip in the "creating and publishing packages" guide, cross-linked from the config entry.Docs URL
https://docs.npmjs.com/cli/v11/using-npm/config#install-strategy