ESLint Flat Config (eslint.config.js) が読み込まれないの主な原因は？

・ESLint のバージョンが v9 未満で flat config 未対応、または v8 では ESLINT_USE_FLAT_CONFIG=true が必要・プロジェクトルートに .eslintrc.* と eslint.config.js が両方存在し、検出ロジックで .eslintrc が優先されている・package.json の type:module 下で CommonJS の eslint.config.js を書き、読み込みに失敗している・プラグイン (eslint-plugin-react など) が flat config 対応版でなく、plugins の宣言形式が legacy と異なる

ESLint Flat Config (eslint.config.js) が読み込まれないの解決策は？

・ESLint を v9 以降に上げる。あるいは v8 系で使うなら ESLINT_USE_FLAT_CONFIG=true 環境変数を付ける・古い .eslintrc.* / .eslintignore を削除し、ignores も eslint.config.js 内に移す・package.json の type フィールドに合わせ、eslint.config.js (ESM) か eslint.config.cjs (CommonJS) を選ぶ・プラグインを flat 対応版に更新し、plugins: { react: pluginReact } の object 形式で読み込む

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

ESLint v9 から flat config が既定。
.eslintrc.* が残っていると衝突する。
eslint.config.js の配置・export 形式・プラグイン側 flat 対応の有無を順に確認する。

#eslint #flat-config #config #migration #v9

公開: 2026-05-22更新: 2026-08-02

実行例あり（2026-08-02 に実環境で検証）

要約

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

よくある原因

ESLint v8 系: flat config は v9 から既定。
v8 では ESLINT_USE_FLAT_CONFIG=true を付けない限り従来形式が優先される
legacy 設定の併存: .eslintrc.json / .eslintrc.cjs / package.json の eslintConfig が残っていると、flat 検出よりそちらが優先されることがある
モジュール形式のミスマッチ: package.json の "type": "module" 下で module.exports を書く、あるいはその逆で読み込みに失敗
プラグインが 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 で確認できる。

実行例

実際に上記の手順を Node.js 20 環境で動かすと、旧 .eslintrc.json のみが存在する状態では ESLint v9.39.4 が eslint.config.(js|mjs|cjs) を見つけられず終了コード 2 で中断し、eslint.config.mjs を配置して再実行した際に no-unused-vars が検出されて終了コード 1 となり、flat config が正常にロードされたことが確認できる。

$ npx eslint --version
v9.39.5

$ npx eslint .
Oops! Something went wrong! :(
 
ESLint: 9.39.5
 
ESLint couldn't find an eslint.config.(js|mjs|cjs) file.
 
From ESLint v9.0.0, the default configuration file is now eslint.config.js.
If you are using a .eslintrc.* file, please follow the migration guide
to update your configuration file to the new format:
 
https://eslint.org/docs/latest/use/configure/migration-guide
 
If you still have problems after following the migration guide, please stop by
https://eslint.org/chat/help to chat with the team.
 
eslint の終了コード: 2

$ rm -f .eslintrc.json

$ npx eslint .
/tmp/tmp.mqPvkCAf8G/index.js
  1:7  error  'unused' is assigned a value but never used  no-unused-vars
 
✖ 1 problem (1 error, 0 warnings)
 
eslint の終了コード: 1（1 = lint 実行され unused を検出＝設定ロードOK）

— 2026-08-02 時点の出力

検証環境

検証日: 2026-08-02
実行環境: node:20

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

要約