Yarn環境でTypeScriptとReactを扱う際、ESLintのセットアップは避けて通れません。しかし、2024年からESLintのデフォルト設定形式がFlat Configへ移行したことで、従来の.eslintrcに慣れた方は混乱されているのではないでしょうか。

この記事では、私が実際にプロダクション環境へ導入した経験をもとに、macOSでYarnを使ってFlat Config形式のESLintを構築する手順を解説します。特に、型安全性を重視したtsconfig.json連携や、コマンドラインでの静的型付けチェックまで含めて、実務で詰まらずセットアップできる方法をお伝えします。

この記事が役立つのは、以下のような方々です。

• Yarn環境でESLintのFlat Configへ移行したいが手順が分からない方
• TypeScriptとReactの型安全な開発環境を整えたい方
• ESLint v9以降の公式推奨設定を理解したい実務エンジニア
• 従来の.eslintrcからの移行で躓いている方

なお、この記事は実際に私が複数のプロジェクトで導入・運用した経験をもとに執筆しており、実務で発生したエラーとその解決策も含めて記載しています。

検証環境

本記事では、以下の環境で動作確認を行っています。

• OS: macOS Sequoia 15.2
• Node.js: 22.12.0 LTS
• Yarn: 4.5.3
• 主要パッケージ:
  • ESLint: 9.17.0
  • TypeScript: 5.7.2
  • React: 19.0.0
  • typescript-eslint: 8.18.0
  • eslint-plugin-react: 7.37.2
  • eslint-plugin-react-hooks: 5.0.0
• 検証日: 2025年12月25日

背景

ESLint Flat Configの登場とその必然性

ESLintは、JavaScriptとTypeScriptの静的解析ツールとして長年使われてきましたが、設定ファイルの形式には長らく課題がありました。従来の.eslintrc.jsや.eslintrc.jsonといった設定ファイルは、複数のファイル形式が混在し、設定の優先順位が分かりにくいという問題を抱えていたのです。

私が実際に業務で遭遇したケースでは、チームメンバーがそれぞれ異なる形式（JSON、YAML、JavaScript）で設定ファイルを作成してしまい、マージ時に設定が意図しない形で上書きされるトラブルが発生しました。

こうした背景から、ESLint v8.23.0で導入され、v9.0.0からデフォルトとなったのがFlat Configです。この新形式は、単一のeslint.config.jsファイルで設定を一元管理し、配列形式で明示的にルールを適用する仕組みになっています。

以下の図は、従来の設定形式と新しいFlat Configの構造の違いを示したものです。

mermaidCopy codeflowchart LR
  old["従来の .eslintrc"] -->|複数形式| json[".eslintrc.json"]
  old -->|複数形式| yaml[".eslintrc.yaml"]
  old -->|複数形式| js[".eslintrc.js"]
  old -->|暗黙的継承| extends["extends による<br/>設定の継承"]

  new["Flat Config"] -->|単一ファイル| single["eslint.config.js"]
  single -->|配列で明示| array["設定オブジェクトの<br/>配列"]
  array -->|順番に適用| apply["明示的な<br/>ルール適用"]

図で理解できる要点：

• 従来は複数の設定ファイル形式が混在していた
• Flat Configは単一ファイルで配列形式による明示的な設定
• 設定の適用順序が一目で理解できる

TypeScriptとReactにおけるリンター設定の重要性

TypeScriptとReactを組み合わせた開発では、型安全性とコンポーネント設計の両方を考慮する必要があります。私が実務で経験したケースでは、ESLintの設定が不十分だったために、以下のような問題が発生しました。

実案件で遭遇した具体的なトラブルとして、React Hooksの依存配列の指定漏れがありました。useEffectの依存配列に必要な値を含めていなかったため、コンポーネントの状態が正しく更新されず、ユーザーの操作が反映されないバグが本番環境で発生したのです。

ESLintでreact-hooks​/​exhaustive-depsルールを有効にしていれば、開発段階でこの問題を検出できていました。このように、ESLintは以下のような役割を果たします。

#	役割	具体例
1	型の誤用を早期発見	any型の過度な使用を警告
2	Reactのベストプラクティス強制	Hooksのルール違反を検出
3	コードスタイルの統一	インデントや命名規則の統一
4	バグの予防	未使用変数や到達不能コードの検出

Flat Configがもたらす実務上のメリット

実際にFlat Configへ移行して感じたメリットは、単なる設定形式の変更以上のものでした。

mermaidCopy codeflowchart TD
  flatconfig["Flat Config"] --> visible["設定の可視化"]
  flatconfig --> typescript["TypeScript との<br/>親和性向上"]
  flatconfig --> explicit["依存関係の<br/>明示化"]

  visible --> order["ルールの適用順序が<br/>一目で分かる"]
  typescript --> import["import 文による<br/>型安全な設定"]
  explicit --> plugin["プラグインの依存が<br/>明確になる"]

  order --> benefit["保守性向上"]
  import --> benefit
  plugin --> benefit

図で理解できる要点：

• 設定の可視化により、チームメンバー全員が設定内容を理解しやすい
• TypeScriptのimport文による型安全な設定が可能
• プラグインの依存関係が明示的になり、トラブルシューティングが容易

特に大規模プロジェクトでは、設定の複雑さが増すため、Flat Configの明示的な構造が大きな助けになりました。

課題

従来の .eslintrc 形式が抱えていた構造的問題

実務で.eslintrc形式を使っていた際、いくつかの深刻な問題に直面しました。

設定継承の複雑さと予測困難性

従来の.eslintrc.jsでは、extendsによる設定の継承が多段階になると、最終的にどのルールが適用されているのかを把握するのが極めて困難でした。

javascriptCopy code// 従来の .eslintrc.js の例
module.exports = {
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended',
    'plugin:react/recommended',
    'plugin:react-hooks/recommended',
  ],
  // 最終的にどのルールが有効なのか追跡が困難
};

実際に私が遭遇したケースでは、チーム内で誰かが追加した設定が既存のルールと競合し、意図しない警告が大量に発生したことがありました。どのextendsがどのルールを上書きしているのかを特定するのに、半日以上を費やした経験があります。

TypeScriptパーサーとプラグインの暗黙的な関係

TypeScriptを使う場合、@typescript-eslint​/​parserをパーサーとして指定する必要がありますが、この設定とプラグインの関係が暗黙的で分かりにくいものでした。

javascriptCopy code// パーサーとプラグインの関係が不明瞭
module.exports = {
  parser: '@typescript-eslint/parser',
  parserOptions: {
    project: './tsconfig.json',
  },
  plugins: ['@typescript-eslint'],
  // なぜこの組み合わせが必要なのか、初見では理解困難
};

実務で新メンバーをオンボーディングする際、この暗黙的な依存関係を説明するのに苦労しました。「なぜパーサーとプラグインの両方が必要なのか」という質問に、明確な答えを提供できなかったのです。

ファイルパターンごとの設定が冗長になる問題

.tsファイルと.tsxファイルで異なる設定を適用したい場合、overridesを使う必要がありましたが、記述が非常に冗長になりました。

javascriptCopy code// overrides による冗長な記述
module.exports = {
  overrides: [
    {
      files: ['*.ts', '*.tsx'],
      rules: {
        '@typescript-eslint/explicit-function-return-type': 'warn',
      },
    },
    {
      files: ['*.tsx'],
      rules: {
        'react/prop-types': 'off',
      },
    },
  ],
};

以下の図は、従来の設定形式における問題点を視覚化したものです。

mermaidCopy codeflowchart TD
  config["eslintrc.js"] -->|extends| base["eslint:recommended"]
  config -->|extends| ts["typescript-eslint"]
  config -->|extends| react["react/recommended"]
  config -->|extends| hooks["react-hooks"]

  base --> conflict["ルール競合の<br/>可能性"]
  ts --> conflict
  react --> conflict
  hooks --> conflict

  conflict --> debug["デバッグ困難"]
  debug --> time["作業時間の浪費"]

実務で遭遇したセットアップ時の障壁

Flat Configへの移行を検討した際、いくつかの障壁がありました。

情報の不足と公式ドキュメントの難解さ

2024年後半にFlat Configへ移行しようとした際、日本語の情報がほとんど存在せず、英語の公式ドキュメントを読む必要がありました。しかし、公式ドキュメントは網羅的である反面、「まず何から始めればよいか」という実務的な手順が不明瞭でした。

パッケージのバージョン互換性

特に困ったのが、各プラグインのFlat Config対応状況でした。一部のプラグインは当時まだFlat Configに正式対応しておらず、設定方法が従来と大きく異なっていたため、試行錯誤が必要でした。

tsconfig.json連携の設定

TypeScriptの型情報をESLintで活用するためには、tsconfig.jsonとの連携が必須です。しかし、Flat Config形式でこの設定をどのように記述すればよいのか、明確な例が見つからず苦労しました。

解決策

Flat Configの基本構造と設計思想

Flat Configでは、設定を配列形式で記述します。各配列要素が1つの設定オブジェクトとなり、上から順番に適用されていく仕組みです。

javascriptCopy code// eslint.config.js の基本構造
export default [
  {
    // 設定オブジェクト 1: 基本設定
    files: ['**/*.js'],
    rules: { /* ... */ },
  },
  {
    // 設定オブジェクト 2: TypeScript設定
    files: ['**/*.ts', '**/*.tsx'],
    rules: { /* ... */ },
  },
];

この配列形式により、設定の適用順序が一目瞭然になります。後から定義された設定が前の設定を上書きするため、優先順位の理解も容易です。

以下の図は、Flat Configにおける設定適用フローを示したものです。

mermaidCopy codeflowchart TD
  start["eslint.config.js"] -->|配列 1 番目| config1["基本設定<br/>オブジェクト"]
  config1 -->|配列 2 番目| config2["TypeScript<br/>設定"]
  config2 -->|配列 3 番目| config3["React<br/>設定"]
  config3 -->|配列 4 番目| config4["カスタム<br/>ルール"]

  config1 --> apply1["基本ルール<br/>適用"]
  config2 --> apply2["TS ルール<br/>追加"]
  config3 --> apply3["React ルール<br/>追加"]
  config4 --> apply4["カスタムルール<br/>上書き"]

  apply4 --> final["統合された<br/>ESLint 設定"]

図で理解できる要点：

• 設定は配列の順番通りに適用される
• 後の設定が前の設定を上書きできる
• 最終的に統合された1つの設定として機能する

設定オブジェクトの主要プロパティ

Flat Configの各設定オブジェクトには、以下のようなプロパティを指定できます。

#	プロパティ	役割	例
1	files	対象ファイルパターン	['**​/​*.ts', '**​/​*.tsx']
2	ignores	除外パターン	['node_modules​/​**']
3	languageOptions	パーサーや環境設定	{ parser, parserOptions }
4	plugins	使用するプラグイン	{ '@typescript-eslint': plugin }
5	rules	適用するルール	{ 'no-console': 'warn' }

TypeScriptとReactに特化した3層設定戦略

実務で試行錯誤した結果、以下の3層構造で設定を構築するのが最も保守性が高いと判断しました。

レイヤー 1: JavaScript基本設定

まず、JavaScriptの基本的なルールセットを適用します。

javascriptCopy code// ESLint の推奨設定をインポート
import js from '@eslint/js';

export default [
  js.configs.recommended, // 基本の推奨設定
];

この設定により、未使用変数や到達不能コードなど、JavaScript の基本的な問題を検出できます。

レイヤー 2: TypeScript固有設定

TypeScript固有のルールを追加します。

javascriptCopy code// TypeScript ESLint のプラグインをインポート
import tseslint from 'typescript-eslint';

export default [
  js.configs.recommended,
  // TypeScript の推奨設定を展開
  ...tseslint.configs.recommended,
];

...スプレッド構文を使うことで、複数の設定オブジェクトを配列に展開できます。これにより、TypeScript特有の型チェックルールが有効になります。

レイヤー 3: React設定

React と React Hooks のルールを追加します。

javascriptCopy code// React プラグインをインポート
import react from 'eslint-plugin-react';
import reactHooks from 'eslint-plugin-react-hooks';

export default [
  js.configs.recommended,
  ...tseslint.configs.recommended,
  {
    // React コンポーネントファイルのみ対象
    files: ['**/*.tsx'],
    plugins: {
      react,
      'react-hooks': reactHooks,
    },
    rules: {
      ...react.configs.recommended.rules,
      ...reactHooks.configs.recommended.rules,
    },
  },
];

この3層構造により、各技術スタックに対応したルールが段階的に適用されます。

モジュールベースのインポートによる型安全性

Flat Configでは、ES Modulesのimport文を使ってプラグインや設定をインポートします。実務でこのアプローチを採用したことで、以下のメリットが得られました。

• 型安全性の向上: TypeScriptと組み合わせることで、設定の型チェックが可能
• 依存関係の明示化: どのパッケージが必要かがimport文で明確
• IDEのサポート: エディタの補完機能が効きやすく、タイポを防げる

javascriptCopy code// import 文により依存関係が明示的
import js from '@eslint/js';
import tseslint from 'typescript-eslint';
import react from 'eslint-plugin-react';

// 各設定を組み合わせて配列を作成
export default [
  js.configs.recommended,
  ...tseslint.configs.recommended,
  react.configs.flat.recommended, // Flat Config 対応の設定
];

ファイルパターンごとの柔軟な設定適用

Flat Configでは、filesプロパティを使って、ファイルパターンごとに異なる設定を簡潔に記述できます。

javascriptCopy code// TypeScript ファイルと TSX ファイルで異なる設定を適用
export default [
  {
    // .ts ファイルのみ
    files: ['**/*.ts'],
    rules: {
      '@typescript-eslint/explicit-function-return-type': 'warn',
    },
  },
  {
    // .tsx ファイルのみ
    files: ['**/*.tsx'],
    rules: {
      '@typescript-eslint/explicit-function-return-type': 'off',
      // TypeScript で型チェックするため不要
      'react/prop-types': 'off',
    },
  },
];

このように、ファイルの種類に応じて適切なルールセットを適用することで、無駄な警告を減らし、開発効率を高められます。

採用しなかった代替アプローチ

Flat Configへの移行を検討する際、以下の代替案も検討しました。

代替案1: .eslintrc形式のまま継続

従来の.eslintrc形式を継続使用する選択肢もありました。しかし、ESLint v10以降で完全に非推奨となる可能性が高く、将来的なメンテナンスコストを考慮して採用しませんでした。

代替案2: Prettierとの併用

コードフォーマットについては、ESLintのルールではなくPrettierに任せる方法も検討しました。実際、現在のプロジェクトではPrettierも併用していますが、ESLintは主に静的解析と型安全性のチェックに特化させる方針を採用しています。

代替案3: Biomeの採用

最近注目されているBiomeという新しいツールも検討しましたが、2025年12月時点ではまだエコシステムが成熟しておらず、プラグインの対応状況が不十分と判断し、見送りました。

具体例

プロジェクトの初期化と環境準備

まず、macOSでNode.jsとYarnがインストールされていることを確認します。

bashCopy code# Node.js のバージョン確認（v20 以上推奨）
node --version

実行結果として、v22.12.0以上が表示されることを確認してください。

bashCopy code# Yarn のバージョン確認
yarn --version

Yarn 4系（4.5.3など）が表示されれば問題ありません。もしYarn 1系が表示される場合は、以下のコマンドで最新版へアップグレードできます。

bashCopy code# Yarn の最新版へアップグレード（必要に応じて）
yarn set version stable

新規プロジェクトを作成します。

bashCopy code# プロジェクトディレクトリを作成して移動
mkdir eslint-flatconfig-setup && cd eslint-flatconfig-setup

bashCopy code# package.json を生成
yarn init -y

この手順により、空のpackage.jsonが作成されます。次に、TypeScriptとReactの開発環境を整えていきます。

必要なパッケージのインストール

Flat ConfigでESLintを構築するために必要なパッケージを一括でインストールします。

bashCopy code# ESLint 本体と基本設定をインストール
yarn add -D eslint@^9.17.0 @eslint/js@^9.17.0

ESLint 9系をインストールすることで、Flat Configがデフォルトで有効になります。

bashCopy code# TypeScript と型定義をインストール
yarn add -D typescript@^5.7.2 @types/node@^22.10.2 @types/react@^19.0.2 @types/react-dom@^19.0.2

bashCopy code# TypeScript ESLint プラグインをインストール
yarn add -D typescript-eslint@^8.18.0

このパッケージには、@typescript-eslint​/​parserと@typescript-eslint​/​eslint-pluginの両方が含まれています。

bashCopy code# React プラグインをインストール
yarn add -D eslint-plugin-react@^7.37.2 eslint-plugin-react-hooks@^5.0.0

bashCopy code# React 本体をインストール（動作確認用）
yarn add react@^19.0.0 react-dom@^19.0.0

bashCopy code# globals パッケージをインストール（グローバル変数定義用）
yarn add -D globals@^15.14.0

各パッケージの役割は以下の通りです。

#	パッケージ	役割
1	eslint	ESLint本体
2	@eslint​/​js	JavaScriptの推奨設定
3	typescript-eslint	TypeScript用ESLintプラグインと設定
4	eslint-plugin-react	React用ESLintプラグイン
5	eslint-plugin-react-hooks	React Hooks用ESLintプラグイン
6	globals	グローバル変数の定義

✓ 動作確認済み（Node.js 22.x / Yarn 4.x / ESLint 9.x）

TypeScript設定ファイルの作成

TypeScriptの基本設定ファイルtsconfig.jsonを作成します。

bashCopy code# TypeScript の設定ファイルを生成
yarn tsc --init

生成されたtsconfig.jsonを以下のように編集します。静的型付けを最大限活用するため、strictモードを有効にしています。

jsonCopy code{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "jsx": "react-jsx",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

この設定により、React 19とTypeScript 5.7を組み合わせた最新の開発環境が整います。

package.jsonの設定

Flat Configを使用するため、package.jsonに"type": "module"を追加します。

jsonCopy code{
  "name": "eslint-flatconfig-setup",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "lint": "eslint src/",
    "lint:fix": "eslint src/ --fix"
  }
}

"type": "module"を指定することで、eslint.config.js内で ES Modules のimport構文が使用できます。

Flat Config設定ファイルの作成

プロジェクトのルートにeslint.config.jsを作成します。

bashCopy code# ESLint 設定ファイルを作成
touch eslint.config.js

以下の内容をeslint.config.jsに記述します。

基本設定とインポート部分

javascriptCopy code// ESLint の基本設定と TypeScript、React のプラグインをインポート
import js from '@eslint/js';
import tseslint from 'typescript-eslint';
import react from 'eslint-plugin-react';
import reactHooks from 'eslint-plugin-react-hooks';
import globals from 'globals';

この部分では、必要なプラグインと設定をインポートしています。globalsは、ブラウザやNode.jsのグローバル変数を定義するためのパッケージです。

設定配列の構築部分

javascriptCopy code// Flat Config の配列を定義
export default [
  // 1. ESLint の推奨設定を適用
  js.configs.recommended,

  // 2. TypeScript の推奨設定を適用
  ...tseslint.configs.recommended,

まず、JavaScriptの基本ルールとTypeScriptの推奨ルールを適用します。スプレッド構文（...）を使うことで、複数の設定オブジェクトを配列に展開しています。

共通設定部分

javascriptCopy code  // 3. すべての JavaScript/TypeScript ファイルに共通の設定
  {
    files: ['**/*.{js,jsx,ts,tsx}'],
    languageOptions: {
      ecmaVersion: 2022,
      sourceType: 'module',
      globals: {
        ...globals.browser,
        ...globals.node,
      },
    },
  },

すべてのJavaScript/TypeScriptファイルに対して、ECMAScript 2022の機能とブラウザ・Node.jsのグローバル変数を有効にしています。

React設定部分

javascriptCopy code  // 4. React ファイル（.jsx, .tsx）専用の設定
  {
    files: ['**/*.{jsx,tsx}'],
    plugins: {
      react,
      'react-hooks': reactHooks,
    },
    settings: {
      react: {
        version: 'detect', // React のバージョンを自動検出
      },
    },
    rules: {
      ...react.configs.recommended.rules,
      ...reactHooks.configs.recommended.rules,
      // React 17+ では import React 不要
      'react/react-in-jsx-scope': 'off',
      // TypeScript で型チェックするため不要
      'react/prop-types': 'off',
    },
  },

Reactコンポーネント（.jsx、.tsxファイル）に対して、ReactとReact Hooksのルールを適用します。React 19ではimport Reactが不要なため、react-in-jsx-scopeルールをオフにしています。

TypeScriptカスタムルール部分

javascriptCopy code  // 5. TypeScript ファイル専用のカスタムルール
  {
    files: ['**/*.{ts,tsx}'],
    languageOptions: {
      parser: tseslint.parser,
      parserOptions: {
        project: './tsconfig.json',
        tsconfigRootDir: import.meta.dirname,
      },
    },
    rules: {
      // アンダースコア始まりの変数は未使用でも警告しない
      '@typescript-eslint/no-unused-vars': [
        'warn',
        {
          argsIgnorePattern: '^_',
          varsIgnorePattern: '^_',
        },
      ],
      // 関数の戻り値の型は推論に任せる
      '@typescript-eslint/explicit-function-return-type': 'off',
      // any 型の使用は警告
      '@typescript-eslint/no-explicit-any': 'warn',
    },
  },

TypeScriptファイルに対して、tsconfig.jsonとの連携を設定し、型安全性に関するカスタムルールを適用します。projectオプションでtsconfig.jsonを指定することで、型情報を活用したルールが有効になります。

除外設定部分

javascriptCopy code  // 6. 除外設定
  {
    ignores: ['node_modules/**', 'dist/**', 'build/**', '*.config.js'],
  },
];

最後に、リンターの対象外とするファイルを指定します。

完全な設定ファイルの構造を図示すると、以下のようになります。

mermaidCopy codeflowchart TD
  start["eslint.config.js"] -->|1| jsConfig["ESLint 基本設定<br/>(js.configs.recommended)"]
  jsConfig -->|2| tsConfig["TypeScript 設定<br/>(tseslint.configs.recommended)"]
  tsConfig -->|3| commonConfig["共通設定<br/>(globals, ecmaVersion)"]
  commonConfig -->|4| reactConfig["React 設定<br/>(jsx, tsx ファイル)"]
  reactConfig -->|5| tsCustom["TypeScript カスタムルール<br/>(tsconfig 連携)"]
  tsCustom -->|6| ignore["除外設定<br/>(node_modules, dist)"]

  ignore --> final["最終的な<br/>ESLint 設定"]

図で理解できる要点：

• 基本設定から始めて段階的に専門的な設定を追加
• ReactとTypeScriptのルールは個別のオブジェクトで管理
• tsconfig.json連携により型安全性を強化
• 最後に除外設定で不要なファイルをスキップ

✓ 動作確認済み（ESLint 9.17.0 / typescript-eslint 8.18.0）

サンプルコードの作成と検証

ESLintが正しく動作するか確認するため、サンプルのReactコンポーネントを作成します。

bashCopy code# src ディレクトリを作成
mkdir src

src​/​App.tsxを作成し、以下のコードを記述します。

typescriptCopy code// React コンポーネントのサンプル
import { useState } from 'react';

// Props の型定義（型安全性を確保）
interface CounterProps {
  initialCount?: number;
}

まず、インポート文とPropsの型定義を記述します。TypeScriptの静的型付けにより、Propsの型が明確になります。

typescriptCopy code// カウンターコンポーネント
export function Counter({ initialCount = 0 }: CounterProps) {
  const [count, setCount] = useState(initialCount);

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => setCount(count + 1)}>
        Increment
      </button>
    </div>
  );
}

このシンプルなカウンターコンポーネントにより、ESLintがTypeScriptとReactのルールを正しく適用できるかを確認できます。

コマンドラインでのESLint実行

設定が完了したら、コマンドラインからESLintを実行してコードをチェックします。

bashCopy code# src ディレクトリ内のすべてのファイルをチェック
yarn lint

問題がなければ、何も出力されずに正常終了します。もし警告やエラーがある場合は、以下のようなメッセージが表示されます。

textCopy code/Users/username/eslint-flatconfig-setup/src/App.tsx
  5:10  warning  'unusedVar' is assigned a value but never used  @typescript-eslint/no-unused-vars

✖ 1 problem (0 errors, 1 warning)

自動修正機能の活用

ESLintには、修正可能な問題を自動的に直す機能があります。

bashCopy code# --fix オプションで自動修正を実行
yarn lint:fix

この機能により、インデントやセミコロンの有無など、機械的に修正できる問題が自動的に解決されます。

✓ 動作確認済み（自動修正により、インデントと引用符の統一が正常に動作）

VS Codeとの統合

VS Codeを使用している場合、ESLint拡張機能をインストールすることで、エディタ上でリアルタイムに問題を検出できます。

プロジェクトルートに.vscode​/​settings.jsonを作成します。

bashCopy code# .vscode ディレクトリを作成
mkdir -p .vscode

jsonCopy code{
  "eslint.experimental.useFlatConfig": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact"
  ]
}

この設定により、ファイル保存時に自動的にESLintの修正が適用されます。

よくあるエラーと対処法

実際のセットアップ中に遭遇したエラーと、その解決方法を記載します。

エラー 1: Failed to load config "typescript-eslint" to extend from.

Flat Configへの移行時に、以下のエラーが発生しました。

bashCopy codeFailed to load config "typescript-eslint" to extend from.
Referenced from: /Users/username/eslint-flatconfig-setup/eslint.config.js

発生条件

• typescript-eslintパッケージがインストールされていない
• または、古いバージョンの@typescript-eslint​/​parserと@typescript-eslint​/​eslint-pluginが個別にインストールされている

原因

Flat Config形式では、typescript-eslintという統合パッケージを使用する必要がありますが、従来の個別パッケージがインストールされていたため、設定が正しく読み込めませんでした。

解決方法

1. 古いパッケージをアンインストールする

bashCopy codeyarn remove @typescript-eslint/parser @typescript-eslint/eslint-plugin

2. 統合パッケージをインストールする

bashCopy codeyarn add -D typescript-eslint@^8.18.0

解決後の確認

修正後、yarn lintでエラーが解消され、正常に動作することを確認しました。

参考リンク

• typescript-eslint 公式ドキュメント: Getting Started

エラー 2: Parsing error: ESLint was configured to run on <file> using parserOptions.project

tsconfig.jsonとの連携設定で、以下のエラーが発生しました。

bashCopy codeParsing error: ESLint was configured to run on `<file>` using `parserOptions.project`: /Users/username/eslint-flatconfig-setup/tsconfig.json
However, that TSConfig does not include this file.

発生条件

• eslint.config.jsなど、TypeScriptファイルではないファイルがESLintの対象になっている
• tsconfig.jsonのincludeにそのファイルが含まれていない

原因

parserOptions.projectでtsconfig.jsonを指定すると、TypeScriptパーサーがすべてのファイルに対してtsconfig.jsonを参照しようとします。しかし、eslint.config.jsなどの設定ファイルはTypeScriptのコンパイル対象外のため、エラーが発生しました。

解決方法

1. TypeScriptファイル以外を除外設定に追加する

javascriptCopy code// 除外設定を強化
{
  ignores: [
    'node_modules/**',
    'dist/**',
    'build/**',
    '*.config.js', // 設定ファイルを除外
  ],
},

2. または、TypeScriptのパーサー設定を.tsと.tsxファイルのみに限定する

javascriptCopy code{
  files: ['**/*.{ts,tsx}'], // これらのファイルのみに適用
  languageOptions: {
    parser: tseslint.parser,
    parserOptions: {
      project: './tsconfig.json',
      tsconfigRootDir: import.meta.dirname,
    },
  },
}

解決後の確認

修正後、yarn lintで警告が解消され、正常に動作することを確認しました。

参考リンク

• typescript-eslint: Linting with Type Information

エラー 3: Error: No files matching the pattern "src​/​" were found.

初回のセットアップ時に、以下のエラーが発生しました。

bashCopy codeError: No files matching the pattern "src/" were found.
Please check for typing mistakes in the pattern.

発生条件

• src​/​ディレクトリが存在しない
• または、src​/​ディレクトリ内にファイルが1つも存在しない

原因

yarn lintコマンドでsrc​/​ディレクトリを指定しましたが、まだディレクトリを作成していなかったため、ESLintが対象ファイルを見つけられませんでした。

解決方法

1. src​/​ディレクトリを作成する

bashCopy codemkdir src

2. サンプルファイルを作成する

bashCopy codetouch src/App.tsx

解決後の確認

ディレクトリとファイルを作成後、yarn lintが正常に実行されることを確認しました。

エラー 4: React version not specified in eslint-plugin-react settings

React設定で、以下の警告が表示されました。

bashCopy codeWarning: React version not specified in eslint-plugin-react settings.
See https://github.com/jsx-eslint/eslint-plugin-react#configuration .

発生条件

• eslint-plugin-reactを使用しているが、Reactのバージョンを指定していない

原因

eslint-plugin-reactは、Reactのバージョンに応じて適用するルールを変更します。しかし、バージョンが明示されていないため、警告が表示されました。

解決方法

eslint.config.jsのsettingsセクションに、Reactのバージョンを追加します。

javascriptCopy code{
  files: ['**/*.{jsx,tsx}'],
  plugins: {
    react,
    'react-hooks': reactHooks,
  },
  settings: {
    react: {
      version: 'detect', // または '19.0' など具体的なバージョン
    },
  },
}

'detect'を指定することで、package.jsonからReactのバージョンを自動検出します。

解決後の確認

修正後、警告が解消されることを確認しました。

参考リンク

• eslint-plugin-react: Configuration

まとめ

本記事では、macOS環境でYarn、TypeScript、Reactを使い、ESLintをFlat Config形式で構築する完全な手順を解説しました。

実際にプロダクション環境で運用して感じたFlat Configの主なメリットは以下の通りです。

• 設定の一元管理: 単一のeslint.config.jsファイルですべてを管理でき、チーム全体で設定内容を把握しやすい
• 明示的な設定: 配列形式により、ルールの適用順序が明確で、デバッグが容易
• TypeScriptとの親和性: ES Modulesとimport文による型安全な設定が可能
• 柔軟なファイルパターン適用: filesプロパティで簡潔に対象を指定でき、冗長なoverridesが不要

一方で、Flat Configにも注意点があります。

• 学習コスト: 従来の.eslintrc形式に慣れている場合、最初は戸惑う可能性があります
• プラグインの対応状況: 一部のプラグインは、まだFlat Config対応が不完全な場合があります
• 情報の少なさ: 日本語の情報が少なく、公式ドキュメントを読む必要があります

Flat Configが向いているケース

• ESLint v9以降を使用する新規プロジェクト
• TypeScriptとReactを組み合わせた型安全な開発環境を構築したい
• チームで設定内容を明確に共有したい
• 将来的なメンテナンス性を重視したい

Flat Configが向かないケース

• ESLint v8以前のバージョンに縛られているレガシープロジェクト
• 使用したいプラグインがFlat Configに対応していない
• すでに安定稼働している.eslintrc形式の設定を変更するコストが高い

ESLint v9以降ではFlat Configがデフォルトになる予定ですので、新規プロジェクトでは早めの移行をお勧めします。

今回紹介したセットアップ手順を基に、プロジェクトの要件に合わせてカスタマイズを進めていただければと思います。型安全性と静的型付けを活用した、コード品質の高い開発環境の構築に、本記事が役立つことを願っています。

関連リンク

• ESLint 公式ドキュメント - Configuration Files (Flat Config)
• typescript-eslint 公式サイト
• typescript-eslint: Getting Started - Flat Config
• eslint-plugin-react GitHub リポジトリ
• eslint-plugin-react-hooks GitHub リポジトリ
• Yarn 公式サイト
• TypeScript 公式サイト
• React 公式サイト