ERR_PNPM_PEER_DEP_ISSUES during CI install: enforce strict peer checks or bypass them in a monorepo?

The Resolution

To resolve ERR_PNPM_PEER_DEP_ISSUES in a pnpm v8 monorepo, you should avoid global bypass flags in CI and instead use pnpm.peerDependencyRules in the root package.json. This allows you to selectively ignore specific version mismatches without disabling the safety checks for the rest of your dependency graph.

Real Issue vs. Overly Strict Range

The distinction depends on whether the library actually executes code from the missing peer at runtime:

• Overly Strict: The library requires ^1.0.0, but you have 1.1.0 installed. If the API is compatible, this is a range mismatch.
• Real Issue: The library requires react as a peer, but react is not installed anywhere in the dependency chain of the consuming package. This will likely cause a Module not found error at runtime.

Implementation: Granular Overrides

Rather than using --no-strict-peer-requirements, add a ruleset to your root package.json. This documents the decision and ensures it is version-controlled.

{
  "pnpm": {
    "peerDependencyRules": {
      "ignoreMissing": [
        "optional-peer-package"
      ],
      "allowAny": [
        "strict-package-with-wrong-range"
      ]
    }
  }
}

Trade-offs: Global vs. Per-Package

Method	Pros	Cons
Global Flag (.npmrc)	Instant CI fix; low effort.	Hides critical missing dependencies; risks runtime crashes.
peerDependencyRules	Explicit; maintains safety for other packages.	Requires manual updates when dependencies change.

Runtime Verification

To verify that a bypassed peer is not actually missing, use the following scoped commands:

1. Inspect the tree: Run pnpm why <peer-package-name> to see if the dependency exists anywhere in the graph for the affected package.
2. Smoke Test: Execute the specific feature of the library that relies on the peer dependency in a production-like environment.
3. Dependency Audit: Run pnpm list to confirm the resolved versions match the expected runtime environment.

Diagnostic Note: Does the error report a missing dependency or a version mismatch? If it is a missing dependency for a package you know is optional, ignoreMissing is the correct path; if it is a version mismatch, allowAny or updating the dependency is required.