Skip to content

Commit 3658bb5

Browse files
docs: recommend install-strategy=linked to catch phantom dependencies (#9690)
Backport of #9678 to `release/v11`. Co-authored-by: Manzoor Wani <[email protected]>
1 parent 774875b commit 3658bb5

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 with the adduser command.

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

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1092,6 +1092,14 @@ place, no hoisting. shallow (formerly --global-style) only install direct
10921092
deps at top-level. linked: install in node_modules/.store, link in place,
10931093
unhoisted.
10941094
1095+
We recommend that package authors use \`--install-strategy=linked\` during
1096+
development to catch undeclared ("phantom") dependencies before publishing:
1097+
the isolated layout only exposes a package's declared dependencies, so an
1098+
\`import\` of a package that was never added to \`package.json\` can fail
1099+
instead of resolving by accident and shipping broken. See [Catching
1100+
undeclared ("phantom")
1101+
dependencies](/using-npm/developers#catching-undeclared-phantom-dependencies).
1102+
10951103
10961104
10971105
#### \`json\`

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

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1209,6 +1209,14 @@ const definitions = {
12091209
nested: (formerly --legacy-bundling) install in place, no hoisting.
12101210
shallow (formerly --global-style) only install direct deps at top-level.
12111211
linked: install in node_modules/.store, link in place, unhoisted.
1212+
1213+
We recommend that package authors use \`--install-strategy=linked\`
1214+
during development to catch undeclared ("phantom") dependencies before
1215+
publishing: the isolated layout only exposes a package's declared
1216+
dependencies, so an \`import\` of a package that was never added to
1217+
\`package.json\` can fail instead of resolving by accident and shipping
1218+
broken. See [Catching undeclared ("phantom")
1219+
dependencies](/using-npm/developers#catching-undeclared-phantom-dependencies).
12121220
`,
12131221
flatten,
12141222
}),

0 commit comments

Comments
 (0)