pnpm install が「ERR_PNPM_PEER_DEP_ISSUES」で失敗する（peer 依存）

要約

ERR_PNPM_PEER_DEP_ISSUES は、パッケージが要求する peer 依存（同じ階層に居てほしい依存）が満たせない、あるいはバージョンが競合しているときに pnpm が install を止めるエラー。
pnpm は peer の扱いが厳格で（How peers are resolved）、strict-peer-dependencies が有効だと警告ではなくエラーになる。
本筋は実際のバージョン不一致を直すこと。
直せない誤検知は設定で個別に黙らせる。

よくある原因

1. strict 設定: strict-peer-dependencies が true で、未充足・不一致をすべてエラーにしている。
2. バージョン不一致: 例えばプラグインが react@^18 を要求しているのに react@19 が入っている。
3. 親の追従遅れ: peer を要求する側が更新されておらず、新しいメジャーに対応していない。
4. 自動補完オフ: auto-install-peers を切っていて、不足 peer が自動で入らない。

解決策

1. まず本当に直す

不足・競合している peer を正しいバージョンで入れる。
これが根治。

pnpm add react@18 react-dom@18

エラーメッセージに「どの依存がどのレンジを要求しているか」が出るので、それに合わせる。

2. 自動インストールと厳格度（設定）

peer を自動で入れたい、または一時的に警告へ下げたいときは設定する（Settings）。

# .npmrc（pnpm-workspace.yaml でも可）
auto-install-peers=true
strict-peer-dependencies=false

3. 個別に許可する（誤検知向け）

追従待ちなど「動くと分かっている」ものは package.json で限定的に許可する。

{
  "pnpm": {
    "peerDependencyRules": {
      "allowedVersions": { "react": "19" },
      "ignoreMissing": ["@types/react"]
    }
  }
}