2
2

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@DaokFrontier

ESLint Flat Config移行ガイド：PrettierとVSCode連携を徹底比較

2
Posted at

ESLint Flat Config移行ガイド：PrettierとVSCode連携を徹底解説（ESLint v9.x対応）

現役エンジニアの皆様、ESLintの新しい設定形式であるFlat Configへの移行はお済みでしょうか？ESLint v9.0.0以降、Flat Configがデフォルトとなり、従来の.eslintrc形式はESLint v10で完全に削除されました。本記事では、ESLint v9.x系を対象に、Flat Configへの移行をスムーズに行うための情報と、Prettier、VSCodeとの連携について詳しく解説します。

1. ESLint Flat Configの概要と主要な変更点

ESLint v9.0.0で導入されたFlat Configは、従来の.eslintrc形式に代わる新しい設定形式です。これにより、ESLintの設定方法が大きく変更されました。

1.1. Flat Configの主な特徴

  • eslint.config.js: プロジェクトのルートに配置される単一のJavaScriptファイルで設定を管理します。ESM (ECMAScript Modules) をサポートし、JavaScriptの柔軟なロジックを直接記述できます。
  • defineConfig(): ESLint v9.0.0で導入されたヘルパー関数です。型安全な設定を記述するために使用され、設定オブジェクトのネスト構造の扱いを簡素化します。
  • extendsの再導入: Flat Configの初期バージョンにはありませんでしたが、ユーザーからのフィードバックを受けて再導入されました。これにより、他の設定（例: @eslint/jsの推奨設定）を容易に組み込めます。
  • ignoresプロパティ: 従来の.eslintignoreファイルに代わり、設定オブジェクトのignoresプロパティで無視するファイルを指定します。
  • languageOptionsプロパティ: ecmaVersion, sourceType, globals, parser, parserOptionsなど、言語関連のオプションをまとめて設定するプロパティです。
  • VS Code ESLint拡張機能 v3.0.5+: Flat Configをサポートするには、VS CodeのESLint拡張機能はバージョン3.0.5以降（プレリリース版を含む）を使用する必要があります。
  • eslint.useFlatConfig設定: VS CodeでFlat Configを有効にするための設定です。settings.jsonに"eslint.useFlatConfig": trueを追加します。ESLint v8.57.0以降で有効です（以前はeslint.experimental.useFlatConfigという実験的な設定でした）。

1.2. Prettierとの連携

PrettierとESLintを連携させる主要なパッケージは引き続きeslint-plugin-prettierとeslint-config-prettierです。

  • eslint-config-prettier: Prettierと競合するESLintのルールを無効化します。これにより、ESLintとPrettierが互いに干渉することなく動作します。
  • eslint-plugin-prettier: PrettierをESLintのルールとして実行します。これにより、ESLintの--fixコマンドでPrettierのフォーマットも適用されます。

2. 実装例

2.1. ESLint Flat Configの基本設定 (eslint.config.js)

ESLintの推奨ルールとPrettierを組み合わせた基本的な設定です。

// eslint.config.js
import globals from "globals";
import js from "@eslint/js";
import prettierRecommended from 'eslint-plugin-prettier/recommended';

export default [
  // グローバルな無視設定
  // dist/, node_modules/, coverage/ ディレクトリ内のファイルを無視する
  {
    ignores: ['dist/', 'node_modules/', 'coverage/'],
  },
  // ESLintの推奨ルールを適用
  js.configs.recommended,
  // 言語オプションの設定
  {
    languageOptions: {
      // ブラウザとNode.jsのグローバル変数を有効化
      globals: {
        ...globals.browser,
        ...globals.node,
      },
      // 最新のECMAScriptバージョンとESモジュールを使用
      ecmaVersion: 'latest',
      sourceType: 'module',
    },
  },
  // Prettierとの連携設定
  // eslint-plugin-prettier/recommended を使用することで、
  // eslint-config-prettier と eslint-plugin-prettier の両方が適用される
  // eslint-config-prettier は、Prettierと競合するESLintルールを無効化する役割
  // eslint-plugin-prettier は、PrettierのフォーマットルールをESLintのルールとして実行する役割
  prettierRecommended,
  // カスタムルール
  {
    rules: {
      // セミコロンを常に必須とする
      "semi": ["error", "always"],
      // constを推奨する
      "prefer-const": "error",
      // その他のプロジェクト固有のカスタムルール
    },
  },
];

2.2. TypeScriptプロジェクトでの設定例

TypeScriptプロジェクトでは、typescript-eslintパッケージを導入し、型チェックを有効にした設定を記述します。

// eslint.config.js
import globals from "globals";
import js from "@eslint/js";
import tseslint from "typescript-eslint";
import prettierRecommended from 'eslint-plugin-prettier/recommended';

export default tseslint.config( // tseslint.config() を使用して型安全な設定を記述
  // グローバルな無視設定
  {
    ignores: ['dist/', 'node_modules/', '**/*.d.ts', 'coverage/'],
  },
  // Prettierとの連携設定
  prettierRecommended,
  // ESLintの推奨ルール
  js.configs.recommended,
  // 言語オプションの設定
  {
    languageOptions: {
      globals: {
        ...globals.browser,
        ...globals.node,
      },
      ecmaVersion: 'latest',
      sourceType: 'module',
    },
  },
  // TypeScriptファイルに適用する設定
  {
    files: ['**/*.ts', '**/*.tsx', '**/*.mts', '**/*.cts'], // TypeScript関連のファイルを指定
    extends: [
      ...tseslint.configs.recommended, // TypeScript ESLintの推奨ルール
      // 必要に応じて型チェックを伴うルールを追加する場合
      // ...tseslint.configs.recommendedTypeChecked, // tsconfig.json の project オプションが必要
    ],
    languageOptions: {
      parser: tseslint.parser, // TypeScriptパーサーを使用
      parserOptions: {
        project: './tsconfig.json', // tsconfig.jsonのパスを指定して型チェックを有効化
        ecmaVersion: 'latest',
        sourceType: 'module',
      },
    },
    rules: {
      // TypeScript固有のカスタムルール
    },
  },
  // JavaScriptファイルに適用する設定 (TypeScriptの型チェックを無効化)
  // .jsファイルに対して誤ってTypeScriptの型チェックが走るのを防ぐ
  {
    files: ['**/*.js', '**/*.mjs', '**/*.cjs'],
    extends: [tseslint.configs.disableTypeChecked],
  }
);

2.3. package.json スクリプトと依存関係

必要なパッケージをインストールし、ESLintとPrettierを実行するためのスクリプトを設定します。

{
  "name": "my-project",
  "version": "1.0.0",
  "description": "ESLint Flat Config Example",
  "main": "index.js",
  "scripts": {
    "lint": "eslint .",
    "lint:fix": "eslint . --fix",
    "format": "prettier --write .",
    "check-format": "prettier --check ."
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "@eslint/js": "^9.0.0",
    "@typescript-eslint/eslint-plugin": "^7.0.0",
    "@typescript-eslint/parser": "^7.0.0",
    "eslint": "^9.0.0",
    "eslint-config-prettier": "^9.0.0",
    "eslint-plugin-prettier": "^5.0.0",
    "globals": "^15.0.0",
    "prettier": "^3.0.0",
    "typescript": "^5.0.0",
    "typescript-eslint": "^7.0.0"
  }
}

2.4. VS Code 設定 (.vscode/settings.json)

VS Codeで保存時に自動フォーマットと自動修正を有効にするための設定です。

{
  "editor.defaultFormatter": "esbenp.prettier-vscode", // デフォルトのフォーマッターをPrettierに設定
  "editor.formatOnSave": true, // 保存時にフォーマットを実行
  "eslint.useFlatConfig": true, // Flat Configを有効化 (ESLint v8.57.0以降)
  "eslint.validate": [ // ESLintを適用する言語の指定
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact",
    "json",
    "jsonc"
  ],
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit" // 保存時にESLintの自動修正を実行
  }
}

editor.formatOnSaveでPrettierによるフォーマットが走り、editor.codeActionsOnSaveでESLintの自動修正が走ります。これにより、保存時に一貫したコードスタイルを維持できます。

3. よくあるエラー・ハマりどころと回避策

3.1. Cannot find config file. または Flat Configが認識されない

  • 原因:
    • ESLintのバージョンがv9.0.0未満。
    • VS CodeのESLint拡張機能がFlat Configを認識していない。
    • eslint.config.jsファイルがプロジェクトのルートにない。
  • 回避策:
    • ESLintのバージョンがv9.0.0以上であることを確認し、必要であればnpm install eslint@latestで更新します。
    • VS CodeのESLint拡張機能が最新のプレリリース版（v3.0.5以上）であることを確認します。
    • settings.jsonに"eslint.useFlatConfig": trueが追加されていることを確認します。
    • eslint.config.jsがプロジェクトのルートに正しく配置されていることを確認します。

3.2. TypeError: ObjectSchema is not a constructor などのESLint内部エラー

  • 原因: ESLintのバージョンとプラグインのバージョンに不整合がある場合に発生しやすいです。特に、異なるパッケージマネージャー（npmとBunなど）を併用している場合に発生することがあります。
  • 回避策:
    • すべてのESLint関連パッケージ（eslint、@typescript-eslint/eslint-plugin、eslint-plugin-prettierなど）を最新バージョンに更新します。
    • 使用しているパッケージマネージャーを統一し、node_modulesを削除してnpm installまたはyarn installを再実行します。

3.3. Key "plugins": This appears to be in eslintrc format (array of strings) rather than flat config format (object).

  • 原因: 従来の.eslintrc形式のプラグイン定義（文字列の配列）をFlat Config形式（オブジェクト）で誤って使用している場合に発生します。
  • 回避策:
    • プラグインはJavaScriptオブジェクトとして直接インポートし、設定オブジェクトの配列内に配置します。pluginsプロパティはFlat Configでは使用しません。
    • 従来の.eslintrc設定をFlat Configに変換する必要がある場合は、@eslint/eslintrcパッケージから提供されるFlatCompatユーティリティの使用を検討します。

3.4. PrettierとESLintの競合

  • 原因: PrettierとESLintの両方がコードのフォーマットに関するルールを持っているため、競合が発生することがあります。
  • 回避策:
    • eslint-plugin-prettier/recommendedをFlat Configに含めます。これは内部的にeslint-config-prettierを適用し、Prettierと競合するESLintのルールを無効化します。また、PrettierのフォーマットルールをESLintのルールとして実行します。
    • eslint.config.jsの配列の最後にprettierRecommendedを配置することで、他のルールよりも優先してPrettierのフォーマットが適用されるようにします。
    • VS Codeのsettings.jsonでeditor.defaultFormatterをPrettierに設定し、editor.codeActionsOnSaveでsource.fixAll.eslintを有効にすることで、保存時にPrettierとESLintが適切に連携して動作します。

4. 設計上のトレードオフとベストプラクティス

Flat Configへの移行は、設定の管理方法に大きな変更をもたらしますが、いくつかの明確なメリットとベストプラクティスが存在します。

  • 単一の設定ファイル: eslint.config.jsという単一のJavaScriptファイルで全ての設定を管理することで、設定の探索が高速化され、設定の複雑さが軽減されます。プロジェクト全体の設定が一覧しやすくなります。
  • JavaScriptベースの設定: 設定ファイルがJavaScriptであるため、より柔軟なロジックや動的な設定が可能です。条件に応じて異なるルールを適用したり、外部データを読み込んだりすることができます。
  • グローバルな無視設定とファイルごとの設定: ignoresプロパティでプロジェクト全体で無視するファイルを指定し、filesプロパティで特定のファイルパターンにのみ適用される設定を定義できます。これにより、TypeScript、JavaScript、JSONなど、異なるファイルタイプに対して最適なルールを適用できます。
  • 設定の階層とマージ: Flat Configでは、設定オブジェクトの配列が上から順に適用され、競合するルールは後から適用されたものが優先されます。これにより、設定の適用順序が明確になり、予期せぬルールのオーバーライドを防ぎやすくなります。
  • 型安全な設定: defineConfig()ヘルパー関数とTypeScriptの型定義を活用することで、設定ミスを減らし、開発体験を向上させることができます。特に大規模プロジェクトでは、設定の保守性を高めます。
  • Prettierとの役割分担: Prettierはコードのフォーマットのみを担当し、ESLintはコード品質と潜在的なバグの検出を担当するという役割分担がベストプラクティスです。eslint-config-prettierとeslint-plugin-prettierを適切に設定することで、この役割分担を効果的に実現し、それぞれのツールの強みを最大限に活かせます。
  • VS Codeの自動フォーマット: editor.formatOnSaveとeditor.codeActionsOnSaveを組み合わせることで、保存時に自動的にPrettierによるフォーマットとESLintによる自動修正が実行され、開発効率が向上します。これにより、コードレビューにおけるスタイル指摘を減らし、本質的な議論に集中できます。

まとめ

本記事では、ESLint v9.xにおけるFlat Configへの移行方法、PrettierおよびVS Codeとの連携について解説しました。Flat Configは従来の.eslintrc形式と比較して、設定の柔軟性、パフォーマンス、保守性の面で多くの改善がされています。

主要なポイントは以下の通りです。

  • eslint.config.jsをプロジェクトルートに配置し、ESM形式で設定を記述します。
  • eslint.useFlatConfig: trueをVS Codeのsettings.jsonに設定し、ESLint拡張機能を最新版に保ちます。
  • eslint-plugin-prettier/recommendedを使用してPrettierとESLintの競合を解消し、両者を連携させます。
  • TypeScriptプロジェクトではtypescript-eslintを導入し、tseslint.config()とprojectオプションを活用して型チェックを有効にします。

これらの設定を適切に行うことで、最新のESLint環境で効率的かつ安定した開発ワークフローを構築できます。

2
2
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
2
2

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?