Peer Dependency Hoisting Across Yarn Workspaces: Unresolved Behavior

Direct answer

In Yarn 2+ (Berry) a peer dependency that appears both as a peer in one workspace and as a regular dependency in another workspace is hoisted to the root virtual store when a single version can satisfy all declared ranges. If the ranges are incompatible, Yarn keeps separate copies per workspace.

Confirmed facts

• Yarn’s resolution algorithm first attempts to satisfy all peer‑dependency requests with a single version that meets the intersection of all ranges; if successful, that version is placed in the root store (classic: node_modules root; PnP: the global .yarn/snapshots map).
• When the intersection is empty, Yarn falls back to workspace‑local copies, leaving each workspace with its own version of the peer.
• The nohoist array blocks hoisting of explicitly listed packages by name. Peer dependencies are resolved implicitly, so nohoist does not automatically prevent their hoisting unless the peer name is added to the array.
• In PnP mode, unhoisted peers appear only in the resolving workspace’s virtual store. The global .yarn/snapshots file does not contain an entry for them, which can cause a "phantom" missing‑module error if code from one workspace tries to require the peer from another workspace’s context.
• packageExtensions can redirect a third‑party package to a different version or source; this may change the peer version seen by the resolver and thus affect whether hoisting occurs, but the behavior is not standardized across Yarn 2.x/3.x releases.

Likely explanation (based on Yarn’s design)

Yarn treats peer dependencies like any other dependency during resolution, but they are not automatically installed unless requested. When a workspace lists a peer, Yarn records a "peer request" that must be satisfied by a version present somewhere in the workspace tree. If another workspace already depends on that same package as a regular dependency, Yarn can satisfy the peer request by using that existing copy, hoisting it to the root to avoid duplication. If the versions conflict, Yarn cannot create a single satisfying copy and therefore isolates the peer per workspace.

Steps to verify the behavior in your repo

1. Identify the peer package name, e.g., react.
2. Run yarn why react from the repository root. The output shows whether react is linked from the root store or from a specific workspace.
3. If using PnP, inspect the resolution map: yarn pnp --mode=json (or look at .yarn/snapshots) and check if react appears under the global __virtual section or only under a workspace‑specific section.
4. To test the effect of nohoist, add the peer name to nohoist in the root package.json, re‑install (yarn install), and repeat yarn why. If the peer remains hoisted, the hoisting was driven by peer‑resolution, not by the nohoist rule.
5. If you suspect a version conflict, examine the declared ranges in each workspace (grep -R "react" workspaces/*/package.json) and note whether they overlap.

What to ask for next

If the peer version ranges across workspaces are incompatible (no overlapping version), the recommendation changes: you must either align the ranges or use yarn resolutions/overrides to force a single version. Please confirm whether the peer’s version specifications overlap across the involved workspaces.