Cutting the node_modules Fat: Why Yarn Plug'n'Play Is Worth the Switch

The problem with node_modules

Large JavaScript projects often grow a node_modules folder that can exceed several gigabytes. That volume comes from thousands of tiny files and the repeated copying of the same package version into many nested directories. The result is slow disk I/O, long clone times, and fragile builds that silently pick up a dependency you never declared.

What Yarn Plug'n'Play actually does

Yarn Plug'n'Play (PnP) replaces the traditional node_modules layout with a single mapping file called .pnp.cjs. During yarn install the package manager stores every dependency in a global cache and writes a lookup table that tells Node.js exactly where to find each package. When your code calls require('lodash'), Node.js asks the PnP resolver for the path to lodash@4.17.21 and receives a direct file‑system location, bypassing the recursive search that normally scans the entire node_modules tree.

Benefits at a glance

• Installation time drops because the manager never copies files into the project folder.
• Disk space shrinks dramatically – the cache holds a single copy of each package.
• Strict dependency resolution: imports that are not listed in package.json throw an error, eliminating ghost dependencies.
• “Zero Installs” possible: the cache can be committed to the repository, so a fresh clone can start a build with yarn install in a few seconds.

Getting started with PnP

To use PnP you need Yarn Berry, the modern 2.x+ release of Yarn. If your project still uses Yarn 1, run:

yarn set version berry

After the switch, enable PnP by adding or updating .yarnrc.yml:

nodeLinker: pnp

Now run:

yarn install

Verification: the project root should contain .pnp.cjs and .yarn/cache, but no node_modules directory. Running a script via Yarn will automatically load the PnP hook:

yarn node index.js

Example – catching a ghost dependency

Suppose react-query depends on axios, but you never listed axios in your own package.json. With PnP the following code will fail:

// index.js
const axios = require('axios');
console.log('Axios loaded');

Run it with:

yarn node index.js

Expected output: a resolution error similar to Cannot find module 'axios'. In a classic node_modules setup, axios would be found automatically because it lives in a nested folder of react-query.

Limitations and compatibility quirks

• Legacy tooling: Build scripts or loaders that expect a physical node_modules directory will break. Many Webpack plugins and older Babel presets contain such assumptions. If you encounter errors, either update the tool to a PnP‑aware version or add a compatibility layer with yarn config set nodeLinker node-modules to revert.
• Native modules: C++ addons that perform require('node_modules/...') lookups may need patching. Yarn provides a node-modules linker that restores the directory, but using it disables the PnP benefits.
• IDE support: Editors like VS Code cannot resolve types or provide autocomplete without the node_modules folder. Install the SDK extension @yarnpkg/sdks and run yarn dlx @yarnpkg/sdks vscode to register the PnP resolver with the editor.
• Node version: PnP requires Node.js 12 or newer. Older runtimes will not load the .pnp.cjs file.

When to adopt PnP

If your project has:

• Large dependency trees or frequent CI builds.
• A need for reproducible dependency graphs.
• Tools that have PnP support or can be updated.

Then PnP can cut install times by an order of magnitude and eliminate duplicate packages.

Rollback in a pinch

Should a critical tool fail, revert to the classic layout by editing .yarnrc.yml:

nodeLinker: node-modules

Run yarn install again. The node_modules folder will be recreated and .pnp.cjs removed.

Next steps

Explore your existing toolchain for PnP compatibility. The Yarn documentation lists a growing set of plugins that support PnP out of the box. If you’re on a mono‑repo, consider enabling PnP for all packages to share a single cache. Finally, commit the .yarn/cache folder and .yarnrc.yml to source control to enable the “Zero Installs” advantage for new contributors.