ESLint 9.0 から導入された Flat Config は、従来の .eslintrc とは全く異なる設定形式です。この記事では、Flat Config の主要な設定項目である files、ignores、plugins、rules、languageOptions の書き方を、速見表とともに詳しく解説します。

速見表：Flat Config 主要設定項目

以下の表は、Flat Config における主要な設定項目を一覧でまとめたものです。各項目の詳細は後続のセクションで解説します。

#	設定項目	役割	記述例	備考
1	files	対象ファイルを指定	files: ['src​/​**​/​*.ts']	glob パターンで記述
2	ignores	除外ファイルを指定	ignores: ['dist​/​**']	glob パターンで記述
3	plugins	プラグインを登録	plugins: { react: reactPlugin }	オブジェクト形式で登録
4	rules	ルールを設定	rules: { 'no-console': 'warn' }	ルール ID と設定値
5	languageOptions	言語設定	languageOptions: { ecmaVersion: 2024 }	パーサー・グローバル変数など

背景

ESLint は長年、.eslintrc.js や .eslintrc.json といった設定ファイル形式を採用してきました。しかし、この形式にはいくつかの課題がありました。

従来の .eslintrc 形式では、設定ファイルが階層的に配置され、親ディレクトリの設定を継承する仕組みになっていました。これは一見便利に見えますが、実際には「どの設定が適用されているのか」を把握するのが難しく、予期しない動作を引き起こすことがありました。

mermaidCopy codeflowchart TD
  root["プロジェクトルート<br/>.eslintrc.js"] --> src["src/<br/>.eslintrc.js"]
  root --> tests["tests/<br/>.eslintrc.js"]
  src --> comp["components/<br/>.eslintrc.js"]

  style root fill:#e1f5ff
  style src fill:#fff4e1
  style tests fill:#fff4e1
  style comp fill:#ffe1e1

図の要点：従来の .eslintrc は階層構造で設定が継承され、複雑化しやすい構造でした。

また、プラグインの指定方法も文字列ベースであり、実際にどのプラグインが読み込まれているのかが不明瞭でした。さらに、extends による設定の拡張も、依存関係が複雑になる原因となっていました。

こうした課題を解決するために、ESLint 9.0 では Flat Config という新しい設定形式が導入されました。Flat Config は、すべての設定を単一の配列として扱い、明示的で予測可能な設定を実現します。

課題

従来の .eslintrc 形式には、以下のような課題がありました。

設定の継承が複雑

.eslintrc は階層的に配置でき、親ディレクトリの設定を自動的に継承します。この仕組みは、大規模なプロジェクトでは「どの設定が適用されているのか」を追跡するのが困難でした。

特に、複数の開発者が関わるプロジェクトでは、意図しない設定の上書きが発生し、デバッグに時間を要することがありました。

プラグインの指定が文字列ベース

従来の形式では、プラグインを文字列で指定していました。

javascriptCopy code// 従来の .eslintrc.js
module.exports = {
  plugins: ['react', 'import'],
  extends: ['plugin:react/recommended'],
};

この方式では、実際にどのプラグインオブジェクトが読み込まれているのかが不明瞭で、バージョン管理やトラブルシューティングが難しくなっていました。

extends による暗黙的な依存

extends を使用すると、他の設定ファイルやプラグインの推奨設定を継承できますが、どのルールが有効になっているのかが分かりにくく、設定の全体像を把握するのが困難でした。

javascriptCopy code// 従来の .eslintrc.js
module.exports = {
  extends: [
    'eslint:recommended',
    'plugin:react/recommended',
    'plugin:@typescript-eslint/recommended',
  ],
};

このような設定では、最終的にどのルールが適用されているのかを確認するには、各 extends の内容を個別に調べる必要がありました。

mermaidCopy codeflowchart LR
  config["設定ファイル"] -->|extends| base1["eslint:recommended"]
  config -->|extends| base2["plugin:react/recommended"]
  config -->|extends| base3["plugin:@typescript-eslint<br/>/recommended"]

  base1 -->|暗黙的| rules1["ルール群 A"]
  base2 -->|暗黙的| rules2["ルール群 B"]
  base3 -->|暗黙的| rules3["ルール群 C"]

  rules1 --> final["最終的な<br/>ルールセット"]
  rules2 --> final
  rules3 --> final

  style final fill:#ffe1e1

図の要点：extends による設定継承は、最終的にどのルールが適用されるのかを把握しづらい構造でした。

解決策

Flat Config は、これらの課題を解決するために設計された新しい設定形式です。主な特徴は以下の通りです。

単一ファイルでの設定管理

Flat Config では、すべての設定を eslint.config.js（または eslint.config.mjs、eslint.config.cjs）という単一のファイルで管理します。

階層的な設定ファイルは使用せず、すべての設定が一箇所に集約されるため、設定の全体像を把握しやすくなります。

配列による設定の定義

Flat Config では、設定を配列として定義します。各要素は設定オブジェクトであり、上から順に適用されます。

javascriptCopy code// eslint.config.js の基本構造
export default [
  {
    // 設定オブジェクト 1
    files: ['**/*.js'],
    rules: { 'no-console': 'warn' },
  },
  {
    // 設定オブジェクト 2
    files: ['src/**/*.ts'],
    rules: { '@typescript-eslint/no-unused-vars': 'error' },
  },
];

この方式では、設定の優先順位が明確で、どの設定がどのファイルに適用されるのかが一目で分かります。

プラグインの明示的なインポート

Flat Config では、プラグインを文字列ではなく、実際のモジュールとしてインポートします。

javascriptCopy code// プラグインのインポート例
import reactPlugin from 'eslint-plugin-react';

export default [
  {
    plugins: {
      react: reactPlugin,
    },
  },
];

この方式により、プラグインのバージョンや実装が明確になり、デバッグやメンテナンスが容易になります。

主要設定項目の概要

Flat Config における主要な設定項目を図解すると、以下のようになります。

mermaidCopy codeflowchart TB
  config["設定オブジェクト"] --> files["files<br/>対象ファイル指定"]
  config --> ignores["ignores<br/>除外ファイル指定"]
  config --> plugins["plugins<br/>プラグイン登録"]
  config --> rules["rules<br/>ルール設定"]
  config --> langOpts["languageOptions<br/>言語設定"]

  files --> filesDetail["glob パターンで<br/>対象を指定"]
  ignores --> ignoresDetail["glob パターンで<br/>除外を指定"]
  plugins --> pluginsDetail["オブジェクトで<br/>プラグインを登録"]
  rules --> rulesDetail["ルール ID と<br/>設定値を指定"]
  langOpts --> langDetail["パーサー、<br/>グローバル変数など"]

  style config fill:#e1f5ff
  style files fill:#fff4e1
  style ignores fill:#fff4e1
  style plugins fill:#fff4e1
  style rules fill:#fff4e1
  style langOpts fill:#fff4e1

図で理解できる要点：

• Flat Config の設定オブジェクトには 5 つの主要項目がある
• 各項目は独立しており、必要なものだけを設定できる
• すべての項目が明示的で、設定の意図が明確

具体例

ここからは、各設定項目の具体的な書き方を詳しく解説します。

files：対象ファイルの指定

files は、ESLint のチェック対象となるファイルを glob パターンで指定します。

javascriptCopy code// 基本的な files の指定
export default [
  {
    files: ['**/*.js'],
  },
];

上記の例では、プロジェクト内のすべての .js ファイルが対象となります。

複数パターンの指定

files には配列で複数のパターンを指定できます。

javascriptCopy code// 複数のファイルパターンを指定
export default [
  {
    files: ['**/*.js', '**/*.mjs', '**/*.cjs'],
  },
];

この設定では、.js、.mjs、.cjs のすべてが対象となります。

ディレクトリを限定した指定

特定のディレクトリ配下のファイルのみを対象とする場合は、以下のように記述します。

javascriptCopy code// src ディレクトリ配下の TypeScript ファイルのみを対象
export default [
  {
    files: ['src/**/*.ts'],
  },
];

files を省略した場合

files を省略すると、すべてのファイルが対象となります。ただし、明示的に指定する方が設定の意図が明確になるため、推奨されます。

ignores：除外ファイルの指定

ignores は、ESLint のチェックから除外するファイルを指定します。これは従来の .eslintignore ファイルに相当します。

javascriptCopy code// 基本的な ignores の指定
export default [
  {
    ignores: ['dist/**', 'build/**', 'node_modules/**'],
  },
];

上記の例では、dist、build、node_modules ディレクトリ配下のすべてのファイルがチェック対象から除外されます。

グローバルな除外設定

設定オブジェクトに files が含まれていない場合、ignores はグローバルな除外設定として機能します。

javascriptCopy code// グローバルな除外設定
export default [
  {
    // files が無いため、グローバルな除外として機能
    ignores: ['**/*.config.js', '**/temp/**'],
  },
  {
    files: ['src/**/*.js'],
    rules: { 'no-console': 'warn' },
  },
];

この設定では、すべての .config.js ファイルと temp ディレクトリ配下のファイルが、すべての設定から除外されます。

ファイル固有の除外設定

特定の設定オブジェクトのみで除外を適用したい場合は、files と ignores を組み合わせます。

javascriptCopy code// src ディレクトリの .js ファイルのうち、test ファイルを除外
export default [
  {
    files: ['src/**/*.js'],
    ignores: ['src/**/*.test.js'],
    rules: { 'no-console': 'warn' },
  },
];

この設定では、src ディレクトリの .js ファイルのうち、.test.js ファイルは no-console ルールの適用から除外されます。

plugins：プラグインの登録

plugins は、使用する ESLint プラグインを登録します。Flat Config では、プラグインを明示的にインポートし、オブジェクトとして登録します。

javascriptCopy code// プラグインのインポート
import reactPlugin from 'eslint-plugin-react';

上記のように、まずプラグインをインポートします。プラグイン名は通常 eslint-plugin- で始まりますが、インポート時にはこの接頭辞を省略できます。

javascriptCopy code// プラグインの登録
export default [
  {
    plugins: {
      react: reactPlugin,
    },
  },
];

plugins オブジェクトのキー（上記の例では react）が、ルールで使用するプラグイン名となります。

複数のプラグインの登録

複数のプラグインを登録する場合は、以下のように記述します。

javascriptCopy code// 複数プラグインのインポート
import reactPlugin from 'eslint-plugin-react';
import importPlugin from 'eslint-plugin-import';
import typescriptPlugin from '@typescript-eslint/eslint-plugin';

javascriptCopy code// 複数プラグインの登録
export default [
  {
    plugins: {
      react: reactPlugin,
      import: importPlugin,
      '@typescript-eslint': typescriptPlugin,
    },
  },
];

プラグイン名にスコープ（@typescript-eslint など）が含まれる場合も、そのまま記述できます。

プラグインとルールの組み合わせ

プラグインを登録した後、そのプラグインのルールを使用できます。

javascriptCopy codeimport reactPlugin from 'eslint-plugin-react';

export default [
  {
    plugins: {
      react: reactPlugin,
    },
    rules: {
      'react/jsx-uses-react': 'error',
      'react/jsx-uses-vars': 'error',
    },
  },
];

ルール名は プラグイン名​/​ルール名 という形式で指定します。上記の例では、react プラグインの jsx-uses-react ルールを使用しています。

rules：ルールの設定

rules は、ESLint のチェックルールを設定します。各ルールには、エラーレベルとオプションを指定できます。

javascriptCopy code// 基本的なルール設定
export default [
  {
    rules: {
      'no-console': 'warn',
      'no-unused-vars': 'error',
    },
  },
];

エラーレベルの指定

ルールのエラーレベルは、以下の 3 つから選択します。

#	エラーレベル	数値	説明
1	'off'	0	ルールを無効化
2	'warn'	1	警告として表示（終了コードは 0）
3	'error'	2	エラーとして表示（終了コードは 1）

文字列または数値で指定できますが、可読性のため文字列の使用が推奨されます。

javascriptCopy code// エラーレベルの指定例
export default [
  {
    rules: {
      'no-console': 'warn', // 警告
      'no-unused-vars': 'error', // エラー
      'no-debugger': 'off', // 無効
    },
  },
];

ルールオプションの指定

多くのルールは、追加のオプションを受け付けます。オプションを指定する場合は、配列形式で記述します。

javascriptCopy code// ルールオプションの指定
export default [
  {
    rules: {
      'no-unused-vars': [
        'error',
        {
          vars: 'all',
          args: 'after-used',
          ignoreRestSiblings: false,
        },
      ],
    },
  },
];

配列の最初の要素がエラーレベル、2 番目以降がオプションとなります。

プラグインのルール設定

プラグインのルールを設定する場合は、プラグイン名​/​ルール名 という形式で指定します。

javascriptCopy codeimport reactPlugin from 'eslint-plugin-react';

export default [
  {
    plugins: {
      react: reactPlugin,
    },
    rules: {
      'react/prop-types': 'off',
      'react/react-in-jsx-scope': 'off',
      'react/jsx-uses-react': 'error',
    },
  },
];

推奨ルールセットの使用

プラグインの推奨ルールセットを使用する場合は、スプレッド構文を使用します。

javascriptCopy codeimport js from '@eslint/js';

export default [
  js.configs.recommended,
  {
    rules: {
      // 推奨設定を上書き
      'no-console': 'warn',
    },
  },
];

@eslint​/​js の configs.recommended は、ESLint の推奨ルールセットを含む設定オブジェクトです。これを配列に展開することで、推奨設定を適用できます。

languageOptions：言語設定

languageOptions は、JavaScript の言語仕様やパーサーに関する設定を行います。

javascriptCopy code// 基本的な languageOptions の設定
export default [
  {
    languageOptions: {
      ecmaVersion: 2024,
      sourceType: 'module',
    },
  },
];

ecmaVersion：ECMAScript のバージョン

ecmaVersion は、使用する ECMAScript のバージョンを指定します。

javascriptCopy code// ECMAScript 2024 を使用
export default [
  {
    languageOptions: {
      ecmaVersion: 2024,
    },
  },
];

最新の機能を使用する場合は 'latest' を指定できます。

javascriptCopy code// 最新の ECMAScript を使用
export default [
  {
    languageOptions: {
      ecmaVersion: 'latest',
    },
  },
];

sourceType：モジュールの種類

sourceType は、ファイルのモジュールタイプを指定します。

#	sourceType	説明
1	'module'	ES モジュール（import/export を使用）
2	'script'	従来のスクリプトファイル
3	'commonjs'	CommonJS モジュール（require/module.exports を使用）

javascriptCopy code// ES モジュールとして扱う
export default [
  {
    languageOptions: {
      sourceType: 'module',
    },
  },
];

parser：カスタムパーサーの指定

TypeScript や Vue などの特殊な構文を解析する場合は、カスタムパーサーを指定します。

javascriptCopy code// TypeScript パーサーのインポート
import typescriptParser from '@typescript-eslint/parser';

javascriptCopy code// TypeScript パーサーの設定
export default [
  {
    files: ['**/*.ts', '**/*.tsx'],
    languageOptions: {
      parser: typescriptParser,
      parserOptions: {
        project: './tsconfig.json',
      },
    },
  },
];

parser にはパーサーオブジェクトを指定し、parserOptions にはパーサー固有のオプションを設定します。

globals：グローバル変数の定義

globals は、コード内で使用できるグローバル変数を定義します。

javascriptCopy code// globals のインポート
import globals from 'globals';

javascriptCopy code// ブラウザ環境のグローバル変数を定義
export default [
  {
    languageOptions: {
      globals: {
        ...globals.browser,
      },
    },
  },
];

globals パッケージを使用すると、browser、node、es2021 などの環境別のグローバル変数セットを簡単に指定できます。

javascriptCopy code// Node.js 環境のグローバル変数を定義
export default [
  {
    languageOptions: {
      globals: {
        ...globals.node,
        ...globals.es2021,
      },
    },
  },
];

カスタムのグローバル変数を定義する場合は、以下のように記述します。

javascriptCopy code// カスタムグローバル変数の定義
export default [
  {
    languageOptions: {
      globals: {
        myCustomGlobal: 'readonly',
        myWritableGlobal: 'writable',
      },
    },
  },
];

値には 'readonly'、'writable'、'off' のいずれかを指定します。

実践的な組み合わせ例

ここまで説明した設定項目を組み合わせた、実践的な設定例を示します。

javascriptCopy code// 必要なモジュールのインポート
import js from '@eslint/js';
import globals from 'globals';
import reactPlugin from 'eslint-plugin-react';
import typescriptParser from '@typescript-eslint/parser';
import typescriptPlugin from '@typescript-eslint/eslint-plugin';

javascriptCopy code// Flat Config の設定
export default [
  // グローバルな除外設定
  {
    ignores: ['dist/**', 'build/**', 'node_modules/**'],
  },

  // JavaScript ファイルの設定
  js.configs.recommended,
  {
    files: ['**/*.js', '**/*.mjs'],
    languageOptions: {
      ecmaVersion: 2024,
      sourceType: 'module',
      globals: {
        ...globals.browser,
        ...globals.node,
      },
    },
    rules: {
      'no-console': 'warn',
      'no-unused-vars': [
        'error',
        { argsIgnorePattern: '^_' },
      ],
    },
  },

  // TypeScript ファイルの設定
  {
    files: ['**/*.ts', '**/*.tsx'],
    languageOptions: {
      parser: typescriptParser,
      parserOptions: {
        project: './tsconfig.json',
      },
    },
    plugins: {
      '@typescript-eslint': typescriptPlugin,
    },
    rules: {
      '@typescript-eslint/no-unused-vars': [
        'error',
        { argsIgnorePattern: '^_' },
      ],
      '@typescript-eslint/explicit-function-return-type':
        'off',
    },
  },

  // React ファイルの設定
  {
    files: ['**/*.jsx', '**/*.tsx'],
    plugins: {
      react: reactPlugin,
    },
    languageOptions: {
      parserOptions: {
        ecmaFeatures: {
          jsx: true,
        },
      },
    },
    rules: {
      'react/prop-types': 'off',
      'react/react-in-jsx-scope': 'off',
    },
  },
];

この設定では、以下のような構造になっています。

mermaidCopy codeflowchart TB
  start["eslint.config.js"] --> ignore["グローバル除外<br/>dist, build, node_modules"]
  start --> js_config["JavaScript 設定<br/>*.js, *.mjs"]
  start --> ts_config["TypeScript 設定<br/>*.ts, *.tsx"]
  start --> react_config["React 設定<br/>*.jsx, *.tsx"]

  js_config --> js_rules["ESLint 推奨ルール<br/>+ カスタムルール"]
  ts_config --> ts_rules["TypeScript ルール<br/>+ パーサー設定"]
  react_config --> react_rules["React ルール<br/>+ JSX 設定"]

  style start fill:#e1f5ff
  style ignore fill:#ffe1e1
  style js_config fill:#fff4e1
  style ts_config fill:#fff4e1
  style react_config fill:#fff4e1

図で理解できる要点：

• 設定は配列で順次適用される
• ファイルパターンごとに異なる設定を適用できる
• グローバルな除外設定を最初に配置し、その後に個別設定を記述する

まとめ

ESLint Flat Config は、従来の .eslintrc 形式の課題を解決する、明示的で予測可能な設定形式です。この記事では、Flat Config の主要な設定項目である files、ignores、plugins、rules、languageOptions の書き方を詳しく解説しました。

Flat Config の主な利点は以下の通りです。

• 明示的な設定：すべての設定が単一ファイルに集約され、全体像を把握しやすい
• 予測可能な動作：配列による順次適用で、設定の優先順位が明確
• プラグインの透明性：プラグインを明示的にインポートし、バージョン管理が容易
• 柔軟な設定：ファイルパターンごとに異なる設定を適用でき、複雑なプロジェクト構成にも対応

速見表を参考にしながら、各設定項目の役割と書き方を理解することで、効果的な ESLint 設定を構築できます。Flat Config への移行は、長期的なメンテナンス性の向上につながりますので、ぜひ積極的に導入を検討してみてください。

関連リンク

• ESLint 公式ドキュメント - Configuration Files (New)
• ESLint 公式ドキュメント - Configuration Files (Deprecated)
• ESLint 公式ドキュメント - Language Options
• ESLint 公式ドキュメント - Plugins
• globals パッケージ
• @eslint/js