ESLint Flat Config で @typescript-eslint/ parser が読み込めない
ESLint v9 の Flat Config では parser の指定方法が変わり、typescript-eslint パッケージから parser オブジェクトを受け取って languageOptions.parser に渡す必要がある。
文字列指定は使えない。
公開: 更新:
npx eslint sample.ts /tmp/tmp.1gbRpeK2Ua/sample.ts 1:8 error Parsing error: Unexpected token : ✖ 1 problem (1 error, 0 warnings)
npx eslint sample.ts
2026-11-16 に node:20(ESLint 9.39.5 / Node.js 20.20.2) で実際に打って取った出力。検証環境の詳細
要約
ESLint v9 系の Flat Config では、TypeScript 用パーサーを文字列名で指定する旧 .eslintrc の書き方は通用しない。typescript-eslint メタパッケージから parser を import し、languageOptions.parser に実体(モジュール)を渡すのが唯一の正しい方法である。
エラーは Key "languageOptions": Key "parser": Expected object with parse() or parseForESLint() method. の形で出る。
実行例
node:20 環境で上記の手順を動かすと、parser 未指定の Flat Config では Parsing error: Unexpected token : が発生し、終了コード 1 になった。languageOptions.parser に typescript-eslint のパーサーを渡すと、終了コードは 0 に切り替わった。
この Unexpected token : は、parser をまったく設定していない場合の現れ方である。
本文冒頭で挙げた Expected object with parse() or parseForESLint() method. は parser に文字列を渡した場合に出て、languageOptions.parser に実体を渡す同じ修正で解消する。
v9.39.5$ npx eslint sample.ts
/tmp/tmp.1gbRpeK2Ua/sample.ts
1:8 error Parsing error: Unexpected token :
✖ 1 problem (1 error, 0 warnings)
$ echo $?
1$ npx eslint sample.ts
$ echo $?
0— 2026-11-16 時点の出力
検証環境Node.js 20.20.2 / npm 10.8.2 / Python 3.11.2 / 2026-11-16 検証(ほか 2 件)
- 検証日
- 実行環境
node:20Debian GNU/Linux 12 (bookworm)- バージョン
- Node.js 20.20.2
- npm 10.8.2
- Python 3.11.2
- Git 2.39.5
- ESLint 9.39.5
この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。
解決策
1. typescript-eslint を導入する
typescript-eslint 公式ドキュメント(新しいタブで開く) が推奨するメタパッケージを使う:
npm install --save-dev typescript-eslint2. tseslint.config() で組み立てる
// eslint.config.js
import eslint from "@eslint/js";
import tseslint from "typescript-eslint";
export default tseslint.config(
eslint.configs.recommended,
...tseslint.configs.recommended,
{
languageOptions: {
parserOptions: {
project: "./tsconfig.json",
tsconfigRootDir: import.meta.dirname,
},
},
},
);tseslint.config は内部で parser をオブジェクトとして組み立ててくれるので、書き手は文字列名を意識する必要がない。
3. 直書きする場合は parser を実体で渡す
import tsParser from "@typescript-eslint/parser";
export default [
{
files: ["**/*.ts", "**/*.tsx"],
languageOptions: {
parser: tsParser,
parserOptions: { project: "./tsconfig.json" },
},
},
];文字列 "@typescript-eslint/parser" を渡すと、Expected object with parse() or parseForESLint() method. で失敗する(ESLint 9.39.5 と 10.14.0 で確認)。
4. 旧 .eslintrc.* を撤去する
ESLint v9 は既定で .eslintrc.* を読まないが、ESLINT_USE_FLAT_CONFIG=false 等で互換モードに落ちていると新旧が混じってデバッグが難しくなる。
移行が完了した時点で旧設定ファイル・.eslintignore をすべて削除する。ignores は新 eslint.config.js の中に書き直す。
ESLint couldn't determine the plugin "@typescript-eslint" uniquely. は parser の指定とは別のエラーで、.eslintrc のモードで出る。
同じプラグインが 2 か所にインストールされていて、2 つの設定ファイルがそれぞれ読み込むと止まる(ESLint 8.57.1 と、ESLINT_USE_FLAT_CONFIG=false の 9.39.5 で確認)。
メッセージに出る 2 つのパスを見て、片方の plugins の指定か、片方のインストールを消す。
Flat Config で同じプラグイン名に別の実体を渡したときは、Cannot redefine plugin "@typescript-eslint" になる。
よくある原因
- 旧
.eslintrcのparser: '@typescript-eslint/parser'をeslint.config.jsにコピペしている。 @typescript-eslint/parserと@typescript-eslint/eslint-pluginを個別に扱い、推奨のメタパッケージtypescript-eslintを経由していない。parserの置き場所をparserOptionsの下にしている(Flat Config ではlanguageOptions.parser)。- ESM / CJS の出力差で parser モジュールが
defaultキー越しに入っているのに、それを直接渡している。