Skip to content

docs: recommend install-strategy=linked to catch phantom dependencies#9678

Merged
owlstronaut merged 1 commit into
npm:latestfrom
manzoorwanijk:docs/linked-strategy-phantom-deps-authors
Jun 29, 2026
Merged

docs: recommend install-strategy=linked to catch phantom dependencies#9678
owlstronaut merged 1 commit into
npm:latestfrom
manzoorwanijk:docs/linked-strategy-phantom-deps-authors

Conversation

@manzoorwanijk

Copy link
Copy Markdown
Contributor

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

@manzoorwanijk manzoorwanijk marked this pull request as ready for review June 26, 2026 18:18
@manzoorwanijk manzoorwanijk requested review from a team as code owners June 26, 2026 18:18
@owlstronaut owlstronaut merged commit fdcfcee into npm:latest Jun 29, 2026
51 checks passed
@github-actions

Copy link
Copy Markdown
Contributor

🎉 Backport to release/v11 created: #9690

@manzoorwanijk manzoorwanijk deleted the docs/linked-strategy-phantom-deps-authors branch June 29, 2026 14:42
owlstronaut pushed a commit that referenced this pull request Jun 29, 2026
…#9690)

Backport of #9678 to `release/v11`.

Co-authored-by: Manzoor Wani <manzoorwani.jk@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[DOCS] Encourage package authors to test under install-strategy=linked to catch phantom dependencies

2 participants