ESLint Flat Configの深淵：プラグインの競合を「科学的」に解決する技術
こんにちは。開発環境の設計に命をかけているエンジニアです。
皆さんは、ESLintの新しい標準である「Flat Config (`eslint.config.js`)」への移行は済みましたか？従来の `.eslintrc` とは異なり、JavaScriptの配列として設定を定義するこの形式は、柔軟性が高い反面、「なぜか意図したルールが効かない」「プラグイン同士が喧嘩して型定義が壊れる」といった、デバッグ困難な迷宮に陥りやすい側面があります。
今日は、特に「複数のプラグインを導入した際の競合」を、ESLintの内部挙動を理解した上でスマートに解決する技術を伝授します。これをマスターすれば、設定ファイルとの睨めっこから解放され、本来のコード開発に集中できるようになりますよ。
—
1. なぜFlat Configで「競合」が起きるのか？
従来のESLintは設定の「マージ」が暗黙的かつ複雑でしたが、Flat Configは非常にシンプルです。「配列のインデックスが若い順に、ルールが上書きされていく」。ただこれだけです。
しかし、ここに落とし穴があります。`eslint-plugin-react` と `eslint-plugin-typescript` を併用する場合、どちらが先にパースを担当するか、あるいはどの設定が後のルールを上書きして無効化しているかを目視だけで追うのは不可能です。
内部モジュール解決の挙動
ESLintは `eslint.config.js` を読み込む際、モジュール解決の過程で依存関係を再帰的に解決します。もしプラグイン間で同じ「LintルールID」を定義していた場合、配列の後方に位置する設定が前の設定を完全に塗り替えます。これが「設定しているはずなのにエラーが出ない」という悪夢の正体です。
—
2. 現場で使える「デバッグ・アーキテクチャ」
設定が意図通りに機能しているか確認するために、最も効率的なのは「ESLintの内部状態を可視化すること」です。
秘伝のコマンド：`–print-config`
ESLintには、現在の設定を解決した結果をJSONとして吐き出す強力なオプションが存在します。
現在の環境で、どのファイルに対してどのようなルールが適用されるかを出力
npx eslint –print-config src/index.ts > resolved-config.json
この `resolved-config.json` を開いてみてください。`rules` セクションには、上書きの結果、最終的に適用されるルールセットがすべて展開されています。ここを見れば、「どのプラグインが、どのルールを上書きしたか」が一目瞭然です。
—
3. 実践：競合を回避する「Flat Config」の書き方
競合を未然に防ぐための、堅牢な `eslint.config.js` のテンプレートです。ポイントは「プラグインの定義」と「ルールの適用」を論理的に分離することです。
// eslint.config.js
import tsPlugin from ‘@typescript-eslint/eslint-plugin’;
import tsParser from ‘@typescript-eslint/parser’;
export default [
{
// 1. グローバル設定：対象ファイルのスコープを明確にする
files: [‘/.{js,ts}’],
languageOptions: {
parser: tsParser, // 型情報を解釈するためのパーサーを明示
parserOptions: { project: ‘./tsconfig.json’ },
},
// 2. プラグイン定義：名前空間をプレフィックスとして保持する
plugins: {
‘@typescript-eslint’: tsPlugin,
},
// 3. ルール設定：明確に優先度をつける
rules: {
‘@typescript-eslint/no-unused-vars’: ‘error’,
‘no-console’: ‘warn’,
},
},
{
// 4. 特定のフォルダだけルールを緩める（オーバーライド）
files: [‘tests//.ts’],
rules: {
‘@typescript-eslint/no-unused-vars’: ‘off’, // テスト時は許容する
},
}
];
この構成のメリット
- 名前空間の分離: `@typescript-eslint` のようにプレフィックスを付けることで、他のプラグイン（例: `import` や `react`）とのルールID衝突を物理的に防ぎます。
- 配列の順序: 前述の通り、配列の後ろにあるオブジェクトが優先されるため、`tests/` などの特定の領域だけ設定を上書きしたい場合、必ず配列の末尾に記述する設計にします。
—
4. 最後に：ツールの本質を理解すること
ESLintやPrettierといったツールは、単なる「警告マシン」ではありません。これらは、あなたのチームが「どのようなコード品質を正義とするか」という合意形成を自動化したものです。
競合が発生したとき、それは「ルールが悪い」のではなく、「複数の正義が衝突している」サインです。`–print-config` で中身を確認し、依存関係の順序を整理する作業は、まさにコードの品質管理をエンジニアリングする行為そのものなのです。
最初は難しく感じるかもしれませんが、この仕組みを理解すれば、どんな大規模なプロジェクトでも迷うことはありません。設定ファイルを「魔法の呪文」から「論理的な設計図」に変えていきましょう。
毎日のコーディングが、今日から少しだけ、心地よいものになりますように。応援しています！