Skip to content

Commit fdcfcee

Browse files
docs: recommend install-strategy=linked to catch phantom dependencies (#9678)
Encourages package authors to develop under `install-strategy=linked` to surface undeclared ("phantom") dependencies before publishing. Under the default hoisted `node_modules`, a package can `import` a dependency it never declared and still resolve it: a transitive dependency hoisted alongside it (or a workspace root's `node_modules`) happens to satisfy the import. That undeclared dependency passes the author's own build silently, then fails for a consumer who installs the package on its own. The linked (isolated) layout exposes only a package's declared dependencies, so such an import can fail at the author's build instead of shipping broken. The change documents this in two places: - The `install-strategy` entry in the config reference now recommends that authors use `--install-strategy=linked` during development, cross-linked to the developers guide. - The Developers guide gains a "Catching undeclared ("phantom") dependencies" section under "Before Publishing", with a note that this is one check — a dependency satisfied by a `devDependency` or a workspace root's `node_modules` can still resolve locally — alongside auditing the dependencies the published package actually uses. This is documentation-only; the config reference text is generated from the `install-strategy` definition description. ## References Closes #9675
1 parent 86416a6 commit fdcfcee

3 files changed

Lines changed: 34 additions & 0 deletions

File tree

‎docs/lib/content/using-npm/developers.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -171,6 +171,24 @@ to install it locally into the node_modules folder in that other place.
171171

172172
Then go into the node-repl, and try using require("my-thing") to bring in your module's main module.
173173

174+
#### Catching undeclared ("phantom") dependencies
175+
176+
Under the default hoisted `node_modules` layout, your package can `import` a dependency it never declared and still resolve it.
177+
A transitive dependency hoisted alongside it, or your workspace root's `node_modules`, happens to satisfy the `import`.
178+
That undeclared ("phantom") dependency passes your own build silently, then fails for anyone who installs your package on its own.
179+
180+
We recommend developing your package under [`install-strategy=linked`](/using-npm/config#install-strategy).
181+
The isolated layout only exposes a package's *declared* dependencies, so an `import` of an undeclared package fails for you during development instead of resolving by accident, shipping broken, and failing for your users:
182+
183+
```bash
184+
npm install --install-strategy=linked
185+
npm test
186+
```
187+
188+
> **Note:** This doesn't catch every case.
189+
> A dependency that's still satisfied at your build by a `devDependency` or by your workspace root's `node_modules` can resolve fine for you and still be missing for whoever installs your package.
190+
> So treat it as one check, not a guarantee, alongside auditing the dependencies your published package actually uses.
191+
174192
### Create a User Account
175193

176194
Create a user account on the [npm website](https://www.npmjs.com/signup).

‎tap-snapshots/test/lib/docs.js.test.cjs‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1192,6 +1192,14 @@ place, no hoisting. shallow (formerly --global-style) only install direct
11921192
deps at top-level. linked: install in node_modules/.store, link in place,
11931193
unhoisted.
11941194
1195+
We recommend that package authors use \`--install-strategy=linked\` during
1196+
development to catch undeclared ("phantom") dependencies before publishing:
1197+
the isolated layout only exposes a package's declared dependencies, so an
1198+
\`import\` of a package that was never added to \`package.json\` can fail
1199+
instead of resolving by accident and shipping broken. See [Catching
1200+
undeclared ("phantom")
1201+
dependencies](/using-npm/developers#catching-undeclared-phantom-dependencies).
1202+
11951203
11961204
11971205
#### \`json\`

‎workspaces/config/lib/definitions/definitions.js‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1278,6 +1278,14 @@ const definitions = {
12781278
nested: (formerly --legacy-bundling) install in place, no hoisting.
12791279
shallow (formerly --global-style) only install direct deps at top-level.
12801280
linked: install in node_modules/.store, link in place, unhoisted.
1281+
1282+
We recommend that package authors use \`--install-strategy=linked\`
1283+
during development to catch undeclared ("phantom") dependencies before
1284+
publishing: the isolated layout only exposes a package's declared
1285+
dependencies, so an \`import\` of a package that was never added to
1286+
\`package.json\` can fail instead of resolving by accident and shipping
1287+
broken. See [Catching undeclared ("phantom")
1288+
dependencies](/using-npm/developers#catching-undeclared-phantom-dependencies).
12811289
`,
12821290
flatten,
12831291
}),

0 commit comments

Comments
 (0)