RFC: Global Virtual Store for Linked Installs

[manzoorwanijk]

Summary

Adds an RFC for an opt-in global-virtual-store config for projects using install-strategy=linked. The projections that linked writes into each project's node_modules/.store/ move to a single machine-global store root; the project's node_modules keeps only the symlinks (junctions on Windows) that linked already creates. Each globally eligible projection is extracted once per machine, so every additional project or git worktree resolving the same dependency subtree costs a few megabytes of symlinks and nearly zero install time.

The proposal changes only @npmcli/arborist and the npm CLI — no changes to pacote, cacache, package-lock.json, the registry, or npm publish.

Motivation

Parallel coding agents have made git worktrees routine, and every worktree pays for a full node_modules today (~2.2 GB and ~24 s per worktree measured on Gutenberg). pnpm shipped enableGlobalVirtualStore for exactly this workload; a 2.5 GB production monorepo measured its node_modules drop to 1.4 MB. A machine-global store is also one of npm's most persistently requested features (#278, #409, #817, npm/cli#8242 — closed with a pointer to this repo; no RFC followed).

With RFC 0042 shipped, the layout already exists: this RFC reparents the store root out of the project, keeping the projection key, the reifier, the symlink shape, and the lockfile unchanged.

Notable semantics

• Requires install-strategy=linked; errors under other strategies.
• Projections become visible only in final form (extract → patch → read-only sweep → atomic rename) and are read-only, files and directories — an in-place write anywhere fails loudly instead of silently corrupting every consumer.
• Packages that may run lifecycle scripts are never globally projected — they stay project-local, exactly as plain linked today. This is stricter than pnpm, which shares built projections (pnpm/pnpm#12302).
• Git dependencies stay project-local (pack output is not reproducible across npm versions, per RFC 0048).
• Garbage collection is exact via a project registry — a projection referenced by a live project is never pruned.
• Hard caveats stated up front: deployment flows that archive node_modules must dereference or reinstall, and the store assumes a single trust boundary.

A separate proposal, RFC: Content-Addressable Store (#912), covers file-level content-addressable storage for every install strategy; the two share a store root layout but neither depends on the other.

See the RFC for the full design, alternatives, implementation plan, tests, and unresolved questions.

---

Disclosure: Claude Code was used to draft this PR description and the initial version of this RFC, and to iterate on it — including adversarial review rounds against the npm CLI source with Codex — before submission.

[manzoorwanijk]

@reggi what do you think about this and #912