Yarn Plug'n'Play: Trading node_modules for a Map

Your node_modules folder is probably the largest, slowest, and least trustworthy directory in your repository. Yarn Plug'n'Play (PnP) replaces it entirely with a single generated file — and in doing so, turns a whole class of silent dependency bugs into loud, immediate errors. It's one of the more opinionated engineering decisions you can make in a JavaScript project, and it's worth understanding before you flip the switch.

What PnP actually changes

With the classic node_modules layout, Node resolves require('lodash') by walking up the filesystem looking for a folder named node_modules/lodash. That traversal is slow, and it has a famous side effect: if any package anywhere in the tree happens to install lodash, your code can import it — even if you never declared it. These are called phantom dependencies, and they work fine right up until a hoisting change silently removes them.

PnP takes a different approach. Instead of a directory tree, Yarn generates one file, .pnp.cjs, containing a lookup table that maps every package name and version to its exact location in a content-addressable cache. When Node asks for a module, Yarn's resolver answers directly from that map. No filesystem traversal, no hoisting, no ambiguity. Repeat installs become near-instant because there's nothing to copy, and installs are deterministic because the map is derived from the lockfile.

The consequence that matters most day to day: importing a package you didn't declare in package.json throws a resolution error immediately. That's not a bug in PnP — it's PnP surfacing a bug in your dependency declarations that node_modules was papering over.

Turning it on

This applies to Yarn 2 and later (the "Berry" line). Yarn 1 is a different tool with different config keys — nothing below transfers to it.

In your project root, with permission to modify the repo:

# Pin the project to a modern Yarn release
yarn set version stable

# .yarnrc.yml
nodeLinker: pnp

yarn install

After the install, verify the outcome: there should be no node_modules directory, and you should see .pnp.cjs at the root. Commit that file — it is your dependency tree now.

One step people forget: editors. TypeScript and ESLint resolve modules through their own logic, so without help they'll report spurious "cannot find module" errors even though builds pass. Run yarn sdks vscode (or the appropriate editor target) to generate SDK shims, commit the .yarn/sdks output if your team shares settings, and point the editor at them.

Zero-Installs: committing the cache

PnP pairs naturally with Zero-Installs, where you also commit the .yarn/cache directory (zip archives of every dependency). A fresh clone then needs no network install at all — yarn install --immutable in CI just validates the lockfile against what's already there. CI gets faster and reproducible by construction.

The cost is real, though: your repository grows by the size of your compressed dependencies, and dependency upgrades produce noisy binary diffs. Some organizations also run security scanners or artifact policies that object to vendored archives in git. If any of that bites, skip Zero-Installs and keep just .pnp.cjs — you still get deterministic resolution, you just pay for a normal cache download on fresh machines.

Where PnP breaks down

The honest trade-off is ecosystem compatibility. Anything that assumes a physical node_modules directory can fail: some bundler configurations, packages with native addons that shell out to paths, older ESLint or TypeScript setups, and historically React Native toolchains. The failure mode is usually an obscure "module not found" deep inside a tool, not a clear PnP error.

You have three escape hatches, in order of preference:

1. Fix the declaration. If your code imports an undeclared package, add it to package.json. This is the most common "breakage" and it's actually the feature working.
2. Patch a third-party package. If a dependency you don't control imports something it never declared, extend it in .yarnrc.yml:

   packageExtensions:
     "some-package@*":
       dependencies:
         missing-dep: "^1.0.0"

3. Fall back for one project. Set nodeLinker: node-modules and keep using modern Yarn's other features with the classic layout. PnP is per-project, not a lifestyle commitment.

Prove it to yourself in ten minutes

The fastest way to evaluate PnP is to watch it catch a phantom dependency. In a scratch project with nodeLinker: pnp, install one package (say, a test framework) and then write a file that imports a package you know exists only as a transitive dependency — something you never declared. Run it: PnP throws a resolution error naming the package and the importer. Now switch the linker to node-modules, reinstall, and run the same file. It succeeds silently. That difference is the entire argument for PnP in one experiment.

Then check the operational side: commit .pnp.cjs and the cache, wipe nothing, and run yarn install --immutable in a clean clone. If it passes without touching the network, your CI story is solid.

The decision

Adopt PnP if you're starting a new project, your toolchain is mainstream (modern TypeScript, ESLint, Jest, esbuild/webpack with current versions), and you value strict dependency hygiene and fast CI. Stay on the node-modules linker if you depend on tools with known PnP gaps, or if your org's repo policies make vendored caches painful. Either way, make the choice deliberately — the worst outcome is discovering phantom dependencies in production because nobody ever turned on the resolver that would have caught them.