npm install --legacy-peer-deps: 依存関係の競合を解決する方法

問題の本質: peerDependenciesの競合

npm v7以降で以下のようなエラーが発生することがあります:

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! 
npm ERR! While resolving: nexttwin@0.1.0
npm ERR! Found: react@17.0.1
npm ERR! node_modules/react
npm ERR!   react@"17.0.1" from the root project
npm ERR! 
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^16.8.0" from react-hook-mousetrap@2.0.4

これは、peerDependencies（ピア依存関係）の競合によるものです。モジュールが期待するバージョンと、プロジェクトで実際にインストールされているバージョンが一致しないために発生します。

peerDependenciesとは

通常の依存関係 (dependencies) との違い

• dependencies: モジュールが動作するために必要なライブラリ（本番環境で必要）
• peerDependencies: モジュールが「互換性があると保証されている」特定のバージョンのライブラリ

具体例

• react-redux の peerDependencies: react と redux
• ブラウザ拡張機能とブラウザの関係に似ています

--legacy-peer-deps の役割

--legacy-peer-deps フラグは、npm v4〜v6の挙動に戻すためのオプションです。具体的には:

• peerDependenciesの自動インストールをスキップ
• 競合が発生しても警告だけでインストールを続行
• 互換性の問題を開発者自身が管理する必要があります

npm install --legacy-peer-deps

いつ使用すべきか

推奨される使用場面

注意点

--legacy-peer-deps はあくまで一時的な解決策として考えましょう

1. React v17/18への移行期: 多くのライブラリが新しいバージョンに対応していない場合
2. 緊急の開発環境: すぐに開発を進める必要がある場合
3. テスト目的: 新しいバージョンで問題がないかを確認したい場合

代替解決策

1. 特定バージョンの強制インストール

npm install react@16.8.0

2. Yarnのresolutions機能の使用

{
  "resolutions": {
    "**/react": "17.0.2",
    "**/react-dom": "17.0.2"
  }
}

3. npmのバージョンダウングレード

# npm v6に戻す
npm install -g npm@6

設定ファイルへの追加

プロジェクトやグローバル設定で永続的に有効にするには:

# プロジェクトの .npmrc に追加
echo "legacy-peer-deps=true" >> .npmrc

# またはグローバル設定
npm config set legacy-peer-deps true

リスクと注意点

重大な注意

--legacy-peer-deps を使用すると、以下のリスクがあります:

1. 互換性問題: バージョンの不一致による実行時エラー
2. 予期しない動作: ライブラリが期待通りに機能しない可能性
3. 将来的な問題: 本番環境で重大な問題が発生するリスク

ベストプラクティス

1. まずはライブラリの更新を確認: 最新バージョンがReact v17/18に対応しているか確認
2. peerDependenciesの確認:

   npm info [package-name] peerDependencies

3. 段階的な移行: 可能な限り正しいバージョンの依存関係を使用
4. テストの徹底: --legacy-peer-deps 使用時は特にテストを強化

まとめ

npm install --legacy-peer-deps はpeerDependenciesの競合を回避する強力なオプションですが、あくまで一時的な解決策として捉えましょう。長期的には、ライブラリの更新や適切なバージョン管理によって、このオプションなしで動作するようにすることが理想的です。

最終手段

どうしても必要な場合のみ使用し、常にリスクを認識した上で活用してください。