Yarn PnP nodeLinker transition and peer dependency consistency

Direct Answer

Yarn does not automatically synchronize peer dependency resolution across workspaces using different nodeLinker strategies. Each workspace resolves peers according to its own linker's rules. A package consuming a peer dependency from a workspace with a different linker will resolve that peer based on the consumer's linker, not the provider's.

How Resolution Differs by Linker

• PnP (nodeLinker: pnp): Peers are hoisted to a single virtual top-level package. The consumer must declare the peer in its own package.json (or via packageExtensions), and Yarn enforces that exactly one version satisfies all dependents.
• node-modules (nodeLinker: node-modules): Traditional nested node_modules with deduplication. Peers can be satisfied by any ancestor node_modules, allowing multiple versions to coexist in different branches.
• pnpm (nodeLinker: pnpm): Content-addressable store with hard links. Enforces strict peer rules like PnP but with a physical store; a peer must be explicitly installed by the consumer or hoisted via pnpm.peerDependencyRules.

Expected Behavior in Mixed Environments

When Workspace A (PnP) provides react@18 as a peer and Workspace B (node-modules) consumes it:

1. Workspace B's resolver looks up react in its own node_modules tree.
2. If Workspace B declares react as a peer but doesn't install it, resolution fails under PnP but may silently succeed under node-modules if a parent workspace hoists it.
3. Version mismatches between workspaces are not reconciled automatically—each linker maintains an independent resolution graph.

Verification Steps

1. Confirm each workspace's effective linker:

   cat .yarnrc.yml | grep nodeLinker
   # Also check per-workspace .yarnrc.yml if present

2. Map peer requirements across workspaces:

   yarn workspaces info --json | jq '.[] | select(.peerDependencies != null) | {name, peerDependencies}'

3. Inspect resolution for a specific peer:

   yarn explain <peer-dep-name> --peers

   This shows which workspaces require the peer and which version each resolves to.
4. After any linker change, regenerate the graph fully:

   yarn cache clean
   rm -rf .yarn/cache .pnp.*
   yarn install
   # Not --mode=skip-build

5. Validate runtime loadability:

   node -e "require('<peer-dep>')"

   Run from each workspace root.

Practical Mitigation

• Standardize on one linker per monorepo (PnP or pnpm recommended for strictness).
• Use workspace:* protocol for internal dependencies to force version alignment.
• Apply packageExtensions or resolutions in the root package.json to normalize peer version ranges.
• Mark peers optional: false (default) to avoid silent differences—optional: true peers are ignored by PnP but installed under node-modules.

One Diagnostic Detail Needed

Which specific peer dependency and workspace pair are you observing inconsistent behavior for? Run yarn explain <that-peer> --peers and share the output—it determines whether the fix is a version alignment, a packageExtensions entry, or a linker standardization.