Pnpm

name: pnpm-peer-dependencies description: Handling peer dependencies with auto-install and resolution rules

pnpm Peer Dependencies

pnpm has strict peer dependency handling by default. It provides configuration options to control how peer dependencies are resolved and reported.

All peer-dependency settings live in pnpm-workspace.yaml (camelCase). The package.json#pnpm field is no longer read.

Auto-Install Peer Dependencies

By default (since v8), pnpm automatically installs missing non-optional peer dependencies:

autoInstallPeers: true

On conflicting requirements (e.g. one dep needs react@^16, another react@^17), pnpm installs nothing and prints a warning - resolve it manually, or opt in to joining the ranges:

autoInstallPeersFromHighestMatch: true   # default false; joins ranges with ||, installs the highest match (react@17)

This also lets pnpm resolve missing required/optional peers from compatible versions elsewhere in the workspace (even with autoInstallPeers: false). A missing optional peer is only resolved if the workspace already has a satisfying version (e.g. from another project's devDependencies). To disable workspace-wide peer reuse, set both autoInstallPeers and dedupePeerDependents to false. Resolved peers are not added to your declared deps: if scripts run a peer's binary, declare it directly.

Strict Peer Dependencies

strictPeerDependencies: true   # default false

When strict, commands fail on a missing or invalid peer dependency in the tree.

Resolve from workspace root

resolvePeersFromWorkspaceRoot: true   # default; install shared peers once at the root

Deduplicate peers

dedupePeerDependents: true   # default; share package instances across projects when peers match
dedupePeers: false           # version-only peer suffixes (name@version), fewer instances
addMissingPeerTypes: false   # v12.12+: every peer `foo` also gets optional peer `@types/foo` (@babel/core -> @types/babel__core)

addMissingPeerTypes helps with enableGlobalVirtualStore, where types installed in your project are otherwise not found next to the package. It changes the lockfile.

Peer Dependency Rules

peerDependencyRules is deprecated (still works): it only silences warnings after resolution. To change declared peer ranges so resolution changes, use overrides with :peer:

overrides:
  'react:peer': '-'                  # remove the peer declaration (and its peerDependenciesMeta)
  'button@2>react:peer': '16 || 17'  # widen the declared peer range
  '@babel/*:peer': '*'

peerDependencyRules:
  ignoreMissing:
    - '@babel/*'
    - eslint
  allowedVersions:
    react: '17 || 18'
  allowAny:
    - '@types/*'

ignoreMissing

Suppress warnings for missing peer dependencies. Patterns: exact name (react), scope (@babel/*), or * (not recommended). Does not support parent>peer selectors.

peerDependencyRules:
  ignoreMissing:
    - '@babel/*'
    - eslint
    - webpack

allowedVersions

Allow specific versions that would otherwise warn. Target a specific parent with parent>peer.

peerDependencyRules:
  allowedVersions:
    react: '17'
    'button@2>react': '17'   # only when react is a peer of button@2

allowAny

Resolve matching peers from any version, ignoring the declared range. Name or glob only (no parent>peer).

peerDependencyRules:
  allowAny:
    - '@types/*'
    - eslint

Adding Peer Dependencies via packageExtensions

Declaratively add a missing peer dependency without JS:

packageExtensions:
  problematic-package:
    peerDependencies:
      react: '*'

For conditional logic, use a readPackage hook in .pnpmfile.mjs instead.

Peer Dependencies in Workspaces

Workspace packages can satisfy peer dependencies:

// packages/app/package.json
{
  "dependencies": {
    "react": "^18.2.0",
    "@myorg/components": "workspace:^"
  }
}

// packages/components/package.json  
{
  "peerDependencies": {
    "react": "^17.0.0 || ^18.0.0"
  }
}

The workspace app provides react which satisfies components' peer dependency.

Common Scenarios

Monorepo with Shared React

# pnpm-workspace.yaml
catalog:
  react: ^18.2.0
  react-dom: ^18.2.0

// packages/ui/package.json
{
  "peerDependencies": {
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  }
}

// apps/web/package.json
{
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:",
    "@myorg/ui": "workspace:^"
  }
}

Suppress ESLint Plugin Warnings

peerDependencyRules:
  ignoreMissing:
    - eslint
    - '@typescript-eslint/parser'

Allow Multiple Major Versions

peerDependencyRules:
  allowedVersions:
    webpack: '4 || 5'
    postcss: '7 || 8'

Debugging Peer Dependencies

# Report unmet/missing peers from the lockfile (exit code 1 on issues; bare `pnpm peers` = check)
pnpm peers check            # also: --json, -r (all workspace projects), -g, --lockfile-only

# See why a package is installed
pnpm why <package>

# Check dependency tree
pnpm list --depth=Infinity

Best Practices

1. Keep autoInstallPeers on for convenience (default in v8+)

2. Use peerDependencyRules instead of blanket-ignoring warnings

3. Document suppressed warnings explaining why they're safe

4. Keep peer ranges wide in libraries (e.g. "react": "^17 || ^18")

5. Run pnpm peers check in CI to catch peer regressions

<!-- Source references: - https://pnpm.io/settings#peerdependencyrules - https://pnpm.io/settings#autoinstallpeers - https://pnpm.io/cli/peers -->