Strict symlink isolation versus selective hoisting for legacy tool compatibility in pnpm workspaces

Question

A pnpm workspace stores packages once in a content-addressable store and creates per-project node_modules via symlinks. Strict isolation preserves deterministic resolution and disk efficiency, but changes resolution paths compared to a flat layout.

Selective hoisting via public hoist patterns and node linker options can expose specific packages at the workspace root to satisfy tools that assume top-level availability. This alters module resolution semantics and can vary with operating system and linker mode.

Concurrent installs share the store and lockfile, which can create contention and perceived latency even when work is deduplicated. The unresolved decision is which packages to hoist or which peer dependency rules to relax for a given workspace without a reproducible rule, requiring per-tool validation.

What criteria define a minimal hoist set that satisfies a legacy tool without weakening isolation? How does hoisting interact with symlink resolution under different node linker modes? Is there a documented way to audit which packages a tool requires at the workspace root?

Tasadduq Burney · Answer

Direct Answer

There is no single documented formula for a minimal hoist set. The criteria are:

Only hoist packages that the legacy tool resolves by walking upward from the workspace root.
Stop adding patterns as soon as the tool runs without MODULE_NOT_FOUND.

Criteria for a Minimal Hoist Set

Tool resolution strategy: Tools that use require.resolve, import(), or spawn child processes from the workspace root (e.g., eslint, jest, webpack CLI) need the target package linked at <workspace-root>/node_modules.
Peer dependencies are irrelevant: Hoisting does not affect peer resolution; peers are still resolved from the dependent package’s own node_modules. Only the tool’s own require calls matter.
Pattern granularity: public-hoist-pattern matches package names (e.g., **/typescript/**), not file paths. You cannot hoist only a subpath of a package.
Stop condition: Add patterns one at a time; after each pnpm install, run the tool. When it succeeds, the current pattern set is minimal for that tool version and workspace layout.

Node-Linker Mode Interactions

Mode	Symlink Behavior	Hoisting Effect
`isolated` (default)	Per-project `node_modules` with symlinks to store; only declared deps reachable	`public-hoist-pattern` creates additional symlinks at workspace root
`hoisted`	Flat `node_modules` at workspace root (npm/yarn style)	`public-hoist-pattern` ignored; everything is already at root
`pnp`	No `node_modules`; `.pnp.cjs` loader intercepts resolution	Hoisting concept does not apply; use `packageExtensions` or `pnpIgnorePatterns` instead

Switching modes requires a clean install (rm -rf node_modules && pnpm install). On Windows, isolated falls back to junctions or copies if symlinks are unavailable, which can change resolution paths; hoisted avoids this.

Audit Procedure (No Built-In Command)

Broad baseline: Temporarily set public-hoist-pattern=["**"] or run pnpm install --shamefully-hoist. This hoists everything and confirms the tool can work.
Trace resolution: Run the tool with NODE_DEBUG=module (Node.js) or DEBUG=resolver (if the tool uses enhanced-resolve). Capture MODULE_NOT_FOUND paths.
Map to packages: Each missing path corresponds to a package name. Add **/<pkg-name>/** to public-hoist-pattern.
Narrow and verify: Remove the broad pattern, run pnpm install, test the tool. Repeat until only necessary patterns remain.
Lock the set: Commit the final pnpm-workspace.yaml patterns. Document the tool version they were validated against.

Verification Commands

# See what would be hoisted without writing to disk
pnpm install --dry-run --reporter=append-only

# List packages currently linked at workspace root
pnpm ls --depth=0 -w

# Compare isolated vs hoisted in a clean temp directory
cp -r . /tmp/test-isolated && cd /tmp/test-isolated && pnpm install
cp -r . /tmp/test-hoisted && cd /tmp/test-hoisted && echo 'node-linker=hoisted' >> .npmrc && pnpm install

One Diagnostic Detail Needed

Which legacy tool (exact package name and version) are you targeting? The hoist set depends on whether it resolves from the workspace root, spawns subprocesses with a different CWD, or uses a custom resolver (e.g., TypeScript's paths, Jest's moduleDirectories). Knowing the tool lets me confirm whether public-hoist-pattern is sufficient or if you need node-linker=hoisted for that tool’s subprocesses.