Switching a Monorepo to Yarn Plug’n’Play: A Practical Guide

Problem: The Node.js Dependency Bloat in Monorepos

Large JavaScript monorepos often ship dozens of packages that share many common dependencies. With the classic node_modules layout, each package can end up pulling its own copy of the same library. This duplication consumes disk space, slows down yarn install, and can lead to subtle version mismatches.

What if you could eliminate the physical node_modules tree entirely, while still keeping deterministic, fast installs?

What Yarn Plug’n’Play (PnP) Is

Plug’n’Play replaces the traditional node_modules directory with a virtual file system. During installation, Yarn generates a .pnp.js file that maps module names to the exact file paths of their contents. When a module is required at runtime, Node.js consults this mapping instead of walking the file system.

Key benefits:

• Disk usage can drop by up to 90% in monorepos with overlapping dependencies.
• Install times improve because Yarn no longer copies files into a large tree.
• Deterministic resolutions: every install yields the same module layout.

Yarn 4 ships with PnP enabled by default, but you can explicitly enable or disable it via the nodeLinker setting.

Enabling PnP in a Monorepo

Step 1 – Add a .yarnrc.yml at the root

Place the following in the repository root to force PnP:

nodeLinker: "pnp"

Alternatively, you can set it globally with yarn config set nodeLinker pnp.

Step 2 – Run yarn install

From the root directory, execute:

yarn install

Yarn will create a .pnp.js file and skip generating node_modules. Verify the file’s presence:

ls -l .pnp.js

Step 3 – Verify Resolution Works

Run a simple Node script or use the REPL to confirm that modules resolve through the virtual path:

node -p "require.resolve('lodash')"

The output should be a path inside /.yarn/cache rather than node_modules/lodash. If you see a physical path, PnP is not active.

Step 4 – Check Yarn’s NodeLinker Setting

Confirm that Yarn reports PnP as the active linker:

yarn config get nodeLinker
# Expected output: pnp

Verifying PnP in Practice

• Presence of .pnp.js – indicates Yarn generated the mapping.
• Resolved paths – compare require.resolve output to physical node_modules paths.
• Yarn config – yarn config get nodeLinker should return pnp.
• Resolution tree – yarn why lodash will list the .pnp.js mapping instead of physical directories.

Trade‑offs & Limitations

Benefit	Trade‑off
Reduced disk usage	Legacy tools that rely on node_modules traversal may break.
Faster installs	Initial yarn install may be slightly slower due to .pnp.js generation.
Deterministic resolution	Debugging resolution can be harder; you need to inspect .pnp.js.
Native module support	Some native addons require additional configuration or PnP‑aware adapters.

In many modern toolchains, PnP is fully supported. However, bundlers like Webpack or tools that perform globbing on node_modules may need plugins (e.g., pnp-webpack-plugin) or fallback to node-modules mode.

Actionable Next Steps

1. Decide if your toolchain is PnP‑ready. Run a quick build or test suite.
2. Enable PnP by adding nodeLinker: "pnp" to .yarnrc.yml.
3. Run yarn install and verify with the checks above.
4. If you encounter failures, either:
   • Configure the affected tool with a PnP adapter, or
   • Temporarily switch back to node-modules with yarn config set nodeLinker node-modules.
5. Once stable, commit the .yarnrc.yml and .pnp.js to your repo, and document the change for your team.

Adopting PnP can drastically reduce your monorepo’s footprint and speed up CI pipelines. Just be mindful of the tooling ecosystem and prepare a fallback plan.