DevToolBox

npm ERESOLVE エラーの原因と解決

npm ERR! ERESOLVE unable to resolve dependency tree は npm 7 以降のピア依存 自動解決に起因します。--legacy-peer-deps で逃げる前に、原因を特定してoverrides で固定するのが本筋です。

ERESOLVEcomes from npm 7's strict peer dependency resolution. Avoid reaching for --legacy-peer-deps first — pin the conflict withoverrides instead.

TL;DR

1. エラーの読み方 / Read the error

npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! While resolving: my-app@1.0.0
npm ERR! Found: react@19.0.0
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^18" from some-lib@3.2.0

上の例は「some-lib@3.2.0 は React 18 を期待しているのに、アプリが React 19 を 入れている」という衝突。解決策は 3 択です。

2. 解決策 3 パターン / Three ways to fix

方法 / Option向き不向き例
ライブラリを上げる最良。メンテ続けるなら必ずこれsome-lib@latest に更新
overrides で固定ライブラリ側が追従しない場合下記コード参照
--legacy-peer-deps一時的な CI パス用。本番NG.npmrc に書くと伝染する

3. overrides の書き方 / Using overrides

// package.json
{
  "overrides": {
    "some-lib": {
      "react": "19.0.0"
    }
  }
}

some-lib から見える React だけ上書きします。トップレベルの React バージョンは 変えないのがミソ。yarn の場合は resolutions、pnpm の場合はpnpm.overrides。

4. 再発予防 / Prevention

5. English summary

ERESOLVEis npm 7's strict peer-dependency check surfacing a real conflict. Read the error to find which package expected which version, then fix in this order: (1) upgrade the offending library, (2) pin with overrides inpackage.json, (3) as a last resort, use--legacy-peer-deps. Never persist --legacy-peer-deps in.npmrc for production — it masks real runtime mismatches.

関連ツール / Related tools

関連ガイド / Related guides