Enabling and Using Yarn Plug’n’Play (PnP) in Yarn 2+ Projects

Why Yarn PnP Matters

Yarn’s Plug’n’Play (PnP) replaces the traditional node_modules directory with a virtual file system that maps module imports to exact locations in the dependency graph. The result is a single source of truth for every package, no duplicate modules, and faster installs. If you want a lean, reproducible environment, PnP is the feature to enable.

Quick Checklist to Turn PnP On

1. Make sure you’re running Yarn Berry (v2 or v3). yarn set version berry will upgrade the CLI if needed.
2. Create or edit .yarnrc.yml in the project root and add pnpMode: strict.
3. Remove any existing node_modules folder to avoid confusion.
4. Run yarn install – a .pnp.cjs file will appear and node_modules will be absent.
5. Run a simple script to verify that imports resolve correctly.

Concrete Example

Assume a fresh Node.js project. The following steps illustrate the full flow.

# 1. Ensure Berry CLI
$ yarn set version berry
# 2. Configure PnP
$ cat > .yarnrc.yml <<'EOF'
pnpMode: strict
EOF
# 3. Clean any legacy node_modules
$ rm -rf node_modules
# 4. Install dependencies
$ yarn install
# 5. Verify PnP file
$ ls -la .pnp.cjs
# 6. Test import
$ node -e "import _ from 'lodash'; console.log(_.chunk([1,2,3,4], 2));"

After step 4, you’ll see a single .pnp.cjs file and no node_modules directory. The runtime will consult the virtual file system defined in that file to locate lodash.

How the Virtual File System Works

• Dependency Graph – Yarn builds a tree of all packages and their versions.
• Exports Field – Packages must expose an exports field in package.json so PnP knows which entry points are valid.
• PnpFallback – For packages that rely on fs-based resolution (e.g., native addons), you can add a pnpFallback entry pointing to the real file path.
• Runtime Hook – Node’s module loader is patched via .pnp.cjs to redirect imports to the correct package location.

Limitations & Common Pitfalls

• No node_modules Means Some Tools Fail – Linters, bundlers, or IDEs that scan for node_modules may throw errors. Configure them for PnP or use the pnpFallback approach.
• Native Modules – Packages that compile native code (e.g., node-sass) require a pnpFallback or a patched package.json to expose the compiled binary.
• Legacy Scripts – Running yarn install --no-lockfile skips PnP generation; always use the default yarn install.
• Mixing Yarn 1 and Berry – Do not use yarn install from Yarn 1 in a Berry repo; it will create a node_modules folder and break resolution.
• Strict vs. Loose – pnpMode: loose allows fallback to node_modules for legacy packages, but it defeats the purpose of strict dependency isolation.

Practical Verification Steps

1. Check Yarn Version – yarn --version should show 2.x or 3.x.
2. Validate PnP File – file .pnp.cjs should exist and node_modules should be absent.
3. Run a Test Import – node -e "import _ from 'lodash'; console.log(_.sum([1,2,3]));" should print 6 without errors.
4. Test a Tool with Fallback – yarn dlx eslint . runs ESLint in a PnP-aware environment. If it fails, add a pnpFallback for the tool’s package.
5. Inspect the Dependency Graph – yarn why lodash will show the exact version and location resolved via PnP.

When to Use pnpMode: loose

For projects that still rely on tools that cannot yet be PnP-aware, loose mode provides a safety net by falling back to node_modules when a package cannot be resolved. However, it introduces duplication and defeats some of the performance gains. Use it only during migration, and aim to switch to strict once all tooling supports PnP.

Conclusion

Enabling Yarn PnP is a straightforward process that yields a lean, deterministic dependency tree. By configuring .yarnrc.yml with pnpMode: strict, removing legacy node_modules, and verifying with simple imports and tool runs, you can confidently adopt PnP in production. Be mindful of native modules and legacy tooling, and use pnpFallback or loose mode only when necessary.