Skip to content

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

Open
manzoorwanijk wants to merge 1 commit into
npm:latestfrom
manzoorwanijk:docs/linked-strategy-phantom-deps-authors
Open

docs: recommend install-strategy=linked to catch phantom dependencies#9678
manzoorwanijk wants to merge 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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

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

1 participant