解決方法：VS Code で ESLint の「Failed to load parser @typescript-eslint/parser」エラーが発生する場合

エラーメッセージ

VS Code で TypeScript ファイルを開き、作業を始めようとした矢先に赤い通知が表示されたり、ESLint の出力コンソールに以下のようなストレスの溜まるメッセージが表示されたりすることがあります。

Failed to load parser '@typescript-eslint/parser' declared in '.eslintrc.js': Cannot find module '@typescript-eslint/parser'

原因の解説

ESLint は簡単に言うと、TypeScript を理解するための「翻訳ガイド」が見つからないと伝えています。@typescript-eslint/parser を使う必要があることは分かっていますが、実際のファイルが存在しないか、エンジンから見えない状態です。主な原因は以下の通りです。

• パッケージがインストールされていない、または誤って削除された。
• モノレポ構成で、VS Code がサブパッケージではなくルートディレクトリを探している。
• パーサーと ESLint プラグインのバージョンが競合している。
• node_modules フォルダが破損している。

ステップ 1: 不足している依存関係をインストールする

まずは基本から確認しましょう。リポジトリをクローンしたばかり、あるいはプロジェクトを初期化したばかりの場合、パーサーが不足している可能性があります。プロジェクトのルートで以下のコマンドを実行し、必要なものがすべて揃っているか確認してください。

# npm を使用する場合
npm install --save-dev @typescript-eslint/parser @typescript-eslint/eslint-plugin eslint

# yarn を使用する場合
yarn add -D @typescript-eslint/parser @typescript-eslint/eslint-plugin eslint

# pnpm を使用する場合
pnpm add -D @typescript-eslint/parser @typescript-eslint/eslint-plugin eslint

常に parser と eslint-plugin はセットでインストールしてください。これらはペアで動作するように設計されており、一方が欠けるとエラーの原因になります。

ステップ 2: バージョン番号を同期させる

バージョンの不一致は、見落としがちなエラーの原因です。パーサーが 7.x.x なのに、プラグインが 6.x.x のままだと、ESLint が正しく動作しないことがあります。package.json を開き、devDependencies セクションを確認してください。

以下のように、メジャーバージョンが正確に一致していることを確認します。

"devDependencies": {
  "@typescript-eslint/eslint-plugin": "^7.2.0",
  "@typescript-eslint/parser": "^7.2.0",
  "eslint": "^8.57.0"
}

ファイルを編集したら、npm install または yarn install を実行して変更を適用します。ここを一致させるだけで、パーサー読み込みエラーの90%は解決します。

ステップ 3: モノレポ向けの VS Code 設定

Nx、Turbo、Yarn Workspaces などのモノレポ構成では、VS Code が node_modules を探す場所を間違えることがよくあります。パーサーが実際には /apps/web/node_modules にあるのに、ルートフォルダを探してしまう場合があります。

これを修正するには、ワークスペースのルートにある .vscode/settings.json ファイルを作成または編集します。

{
  "eslint.workingDirectories": [
    { "mode": "auto" }
  ]
}

もし "auto" で解決しない場合は、明示的に指定してみてください。VS Code にプロジェクトの場所を正確に伝えます。

{
  "eslint.workingDirectories": [
    "./apps/frontend",
    "./apps/backend",
    "./packages/shared-ui"
  ]
}

ステップ 4: 最終手段（クリーン再インストール）

時として、依存関係ツリーが複雑に絡み合ってしまうことがあります。バージョンやパスを確認しても解決しない場合は、node_modules フォルダを一度削除しましょう。これにより、ゴーストファイルや破損したシンボリックリンクをクリアできます。

# フォルダとロックファイルを削除
rm -rf node_modules
rm package-lock.json # または yarn.lock / pnpm-lock.yaml

# 再インストール
npm install

ステップ 5: ESLint サーバーを強制再起動する

VS Code は古いエラーをキャッシュすることで知られています。ディスク上のファイルは修正済みでも、ESLint 拡張機能が古い「失敗した」状態を見続けていることがあります。PC を再起動する必要はありません。サーバーだけを再起動しましょう。

• Ctrl + Shift + P（Mac の場合は Cmd + Shift + P）を押します。
• 「ESLint: Restart ESLint Server」 と入力します。
• Enter キーを押し、数秒待ちます。

確認

実際に直ったか確認しましょう。VS Code で .ts ファイルを開き、下部のステータスバーを確認します。小さな「ESLint」アイコンが表示されているはずです。チェックマークが付いているか、アイコンに何も付いていなければ成功です。赤い「x」が表示されている場合は、それをクリックして 出力 (Output) パネルを開き、残りのエラーを確認してください。

クイックヒント

• グローバルインストールを避ける: npm install -g eslint は絶対に実行しないでください。グローバルなパーサーはローカルプロジェクトのバージョンと競合しやすく、今発生しているようなエラーを招く原因になります。
• Node のバージョンを確認する: ESLint 9 を動かそうとしているのに Node のバージョンが非常に古い（v14 など）場合、互換性の壁に突き当たります。nvm を使用して、v20 などの最新の LTS バージョンを使用するようにしてください。