Adopting Yarn Plug'n'Play on Node.js 20: what breaks when node_modules disappears?

What Breaks When node_modules Disappears

Moving to Yarn 4 Plug'n'Play (PnP) replaces the physical node_modules tree with a static mapping file (.pnp.cjs). This breaks any tool or package that relies on filesystem-based module resolution rather than the Node.js resolution algorithm.

High-Risk Package Categories

• Native Binaries and node-gyp: Packages that compile C++ addons often expect a node_modules directory to locate headers or write compiled artifacts during postinstall. If the build script uses hardcoded relative paths to node_modules, the installation will fail.
• Tooling with Hardcoded Paths: Older Babel plugins, TypeScript transformers, or custom build scripts that manually traverse the filesystem (e.g., fs.readFileSync('node_modules/package/package.json')) will throw "File not found" errors.
• Phantom Dependency Users: PnP enforces strict resolution. If Package A uses Package C, but only declares Package B as a dependency (relying on Package B to pull in C via node_modules hoisting), PnP will block the access to Package C.
• Peer-Heavy Libraries: Libraries with complex peer dependency chains may surface resolution errors if the host environment does not strictly satisfy the peer requirements, as PnP does not "guess" the location of peers.

Selective Linker Fallback

In Yarn 4, you cannot mix linkers within a single package, but you can configure the linker globally or use packageExtensions to fix metadata. To handle problematic packages that absolutely require a physical tree, you have two primary options:

1. Global Fallback: Set nodeLinker: node-modules in .yarnrc.yml. This disables PnP entirely for the workspace, returning to the classic layout.
2. PnP-to-node-modules Migration: If only a few packages fail, use packageExtensions in .yarnrc.yml to manually add missing peer dependencies or dependencies that were previously hoisted. This allows you to keep PnP active while satisfying the strict resolution requirements of legacy packages.

CI Caching Strategy Changes

Caching node_modules is obsolete under PnP. Your CI pipeline must be updated to cache the following instead:

• The Yarn Cache: .yarn/cache (the content-addressable store).
• The PnP Map: .pnp.cjs and .pnp.cjs.meta.

Because PnP uses a global cache and a mapping file, CI restores are typically faster and more reliable than copying thousands of small files in a node_modules directory.

Verification Steps

To validate the migration on Node.js 20, run these scoped checks:

# Verify native addon loading
node -e "require('your-native-package')"

# Check for undeclared dependencies (PnP will throw errors here)
yarn run test

Diagnostic Detail Needed: Do you use any legacy build tools (e.g., Webpack 4 or older Gulp plugins) that are not updated for Yarn 4? This determines if you will need the pnpify wrapper for your build pipeline.