ESLint Flat Config (eslint.config.js) が読み込まれない

要約

eslint.config.js が認識されない場合、(1) ESLint バージョンが v9 未満 / (2) 旧 .eslintrc.* が残って優先される / (3) ESM / CommonJS の取り違え / (4) プラグインが flat 未対応 — のいずれかが原因。eslint --print-config <file> を使えば実際に適用されている設定が読み取れる。

よくある原因

1. ESLint v8 系: flat config は v9 から既定。
   v8 では ESLINT_USE_FLAT_CONFIG=true を付けない限り従来形式が優先される
2. legacy 設定の併存: .eslintrc.json / .eslintrc.cjs / package.json の eslintConfig が残っていると、flat 検出よりそちらが優先されることがある
3. モジュール形式のミスマッチ: package.json の "type": "module" 下で module.exports を書く、あるいはその逆で読み込みに失敗
4. プラグインが flat 未対応: 旧 extends: ["plugin:react/recommended"] 形式しか提供していないプラグインは flat config の plugins object 記法では使えない

解決策

1. バージョンを上げる

npm install --save-dev eslint@latest
npx eslint --version   # 9.x.x 以上

公式の設定ファイル一覧 のとおり、v9 以降は eslint.config.js / eslint.config.mjs / eslint.config.cjs を自動で検出する。

2. 旧設定を削除する

rm -f .eslintrc .eslintrc.* .eslintignore
# package.json の "eslintConfig" キーも削除

ignore 設定は flat config 内に書く。

// eslint.config.js
export default [
  { ignores: ["dist/**", "node_modules/**"] },
  // ...
];

詳しい移行は migration-guide を参照。

3. モジュール形式を合わせる

package.json に "type": "module" がある場合は ESM で書く。

// eslint.config.js (ESM)
import js from "@eslint/js";
 
export default [
  js.configs.recommended,
  { rules: { "no-unused-vars": "warn" } },
];

CommonJS プロジェクトでは拡張子を .cjs にする。

// eslint.config.cjs
const js = require("@eslint/js");
module.exports = [js.configs.recommended];

4. プラグインの flat 対応を確認

import pluginReact from "eslint-plugin-react";
 
export default [
  {
    files: ["**/*.{jsx,tsx}"],
    plugins: { react: pluginReact },
    rules: { "react/jsx-key": "error" },
  },
];

pluginReact.configs.flat.recommended が用意されていればそれを展開して使う。
プラグインが flat 未対応なら @eslint/eslintrc の FlatCompat で legacy 設定を取り込む手もあるが、可能ならプラグイン側を更新する。
実際に適用されている設定は npx eslint --print-config path/to/file.js で確認できる。