npm 11.5.0でoptional peer dependenciesがインストールされない問題

起こったこと

npm 11.5.0以降で以下の問題が発生しています、node24にバージョンアップする過程でnpm11.5.0以降にしようとしたら出たのでメモ

• npm ciやnpm installが成功で終わる
• しかし実際には必要なパッケージがインストールされていない
• 実行時に「Cannot find module」エラーが発生

具体例

@nestjs/graphqlを使っているプロジェクトの場合：

@nestjs/graphqlのpeerDependencies:

{
  "peerDependencies": {
    "@nestjs/common": "^10.0.0 || ^11.0.0",
    "class-validator": "^0.14.0"
  },
  "peerDependenciesMeta": {
    "class-validator": {
      "optional": true
    }
  }
}

npm 11.4.0以前：

• class-validatorも一緒にインストールされる
• package-lock.jsonに記録される
• 問題なく動作はする

npm 11.5.0以降：

• class-validatorがインストールされない（optional: trueだから）
• package.jsonに直接書かれていないのでスキップ

peer dependencyとoptional: trueとは

peer dependency

「このライブラリを使うなら、お前のプロジェクトに特定のライブラリが入っている前提で作ってるからな・・・？」

optional: true

"peerDependenciesMeta": {
  "class-validator": {
    "optional": true
  }
}

• 「あれば便利だけど、なくても基本機能は動く」
• 「インストール失敗しても続行していい」

optional: true

npm 11.5.0のバグ：

• 「package-lock.jsonに記録されていても無視していい」と誤解釈
• 実際に使っているのにインストールされない

バグの本質

package-lock.jsonに記録されている = 過去に誰かがインストールした = 使っている可能性が高い

それをスキップする理由はありません。optional: trueは「インストールしない理由」ではなく「失敗しても続行していい」

現在の状況

issue 上がってた
https://github.com/npm/cli/issues/8464