Enabling Yarn Plug'n'Play (PnP) in a Node.js Project: A Step‑by‑Step Guide

Desired Outcome

Convert a classic node_modules layout to Yarn’s Plug’n’Play (PnP) system, eliminating the folder and speeding up install times while keeping dependency resolution deterministic.

Prerequisites

• Node.js 14+ (LTS is recommended).
• Yarn 2 or newer (Yarn 1 – “classic” – does not support PnP).
• Project already initialized with yarn init or contains a package.json.
• Write permissions to the project root (no root or sudo required).

Procedure

1. Verify Yarn version

   Run yarn --version and ensure the output is >= 2.0.0.

   yarn --version
   # Expected: 2.x.x or newer
   

2. Create or update .yarnrc.yml

   Place the following in the project root. If the file already exists, add or replace the nodeLinker key.

   nodeLinker: pnp
   # Optional: enable a fallback to node_modules for problematic packages
   # pnpFallbackMode: node-modules
   

3. Install dependencies

   Run yarn install. Yarn will generate a .pnp.js (or .pnp.cjs in newer releases) instead of populating node_modules.

   yarn install
   

4. Verify PnP is active
   • Check that .pnp.js exists in the project root.
   • Test a runtime import: node -e "require('lodash')" should output nothing and exit with code 0.
   • Run yarn why lodash and confirm the resolution path points to .pnp.js rather than node_modules.

   # Verify file
   ls -l .pnp.js
   # Runtime test
   node -e "require('lodash')"
   # Yarn why
   yarn why lodash
   

5. Handle native or __dirname‑dependent packages

   Some packages that rely on __dirname or native bindings may fail. If you encounter such errors, consider adding a fallback:

   pnpFallbackMode: node-modules
   

   Then re‑run yarn install.

6. Test application and build scripts

   Run your usual start or build commands (e.g., npm run start or yarn build) and watch for import errors. If everything compiles and starts, PnP is working.

Expected Checks

• .pnp.js file present.
• Runtime import test succeeds without errors.
• No node_modules folder is created.
• Yarn’s dependency graph shows PnP resolution (use yarn why).

Recovery Options

• Revert to node_modules

  Change .yarnrc.yml back to nodeLinker: node-modules and run yarn install again. This restores the classic layout.

  nodeLinker: node-modules
  

• Isolate problematic packages

  Use pnpFallbackMode: node-modules or add --ignore-engines for specific engines that conflict.

• CI artifacts

  Ensure your CI pipeline includes .pnp.js in the build artifacts; otherwise imports will fail.

• Check peer dependencies

  If PnP throws a missing peer dependency error, add the peer explicitly to dependencies or devDependencies.

Limitations & Notes

• Yarn PnP is not supported in Yarn 1 (“classic”). Verify you’re on Yarn 2+.
• Packages with native bindings may require re‑builds or patches to work under PnP.
• Some tooling (e.g., certain linters or test runners) may need configuration changes to recognize PnP.
• Always run a full test suite after enabling PnP to catch subtle runtime issues.