Yarn PnP nodeLinker configuration for native binary compatibility

Answer the exact question first

What triggers Yarn to move a package to the unplugged directory automatically?

• Any dependency that declares an install, preinstall or postinstall script in its package.json will be unplugged. Yarn executes those scripts in a real filesystem context, so the package must be materialised on disk.
• A package that sets preferUnplugged: true in its own package.json is also unplugged, regardless of whether it has install scripts.
• In Yarn 4 and later, packages that expose a node_modules field or contain native bindings that probe __dirname at runtime may be unplugged, but this is not an automatic trigger; it is recommended to test such packages manually.

Is there a configuration property to explicitly define a list of packages that must be unplugged regardless of detected binary presence?

• Yes. In the root package.json, add a dependenciesMeta section and set unplugged: true for any package you want to force‑unplug.
• Example:

{
  "name": "my‑app",
  "private": true,
  "dependencies": {
    "node‑git": "^1.0.0",
    "sharp": "^0.32.0"
  },
  "dependenciesMeta": {
    "node-gyp": { "unplugged": true },
    "sharp@^0.32.0": { "unplugged": true }
  }
}

Yarn will then place node-gyp and sharp under .yarn/unplugged even if it does not detect install scripts or native binaries.

Verification steps

1. Run yarn install after editing package.json.
2. Check that the packages appear under .yarn/unplugged.
   • Example: ls .yarn/unplugged/node-gyp should list the real folder.
3. Use yarn unplug <package> to force‑unplug a single package and confirm it is extracted.
4. Run node -e "require.resolve('sharp')" to ensure the module resolves to the physical path, not a zip archive.

Ask for missing diagnostic detail

To ensure the guidance applies to your environment, please confirm the Yarn version you are using (e.g., yarn --version). The dependenciesMeta.unplugged flag was introduced in Yarn 3.0, and its exact behaviour may vary slightly in later releases.

Key takeaways

• Automatic unplug occurs only when install scripts or preferUnplugged are present.
• Use dependenciesMeta in the root package.json to force‑unplug arbitrary packages.
• After any change, run yarn install or yarn rebuild to regenerate the .pnp.cjs mapping.
• Keep the forced‑unplug list minimal to preserve PnP benefits.