TypeScript プロジェクトに ESLint v9 + Prettier を導入する

TypeScript プロジェクトに ESLint v9 + Prettier を導入する

2025.08.03

こんにちは、製造ビジネステクノロジー部の若槻です。

昨年4月に ESLint v9 がリリースされました。v9 では、ESLint の設定ファイルの形式が大きく変更され、これまでの .eslintrc.js.eslintrc.json から eslint.config.js という新しい形式(Flat Config)に移行することが推奨されています。

https://eslint.org/docs/latest/use/configure/configuration-files

今回は、TypeScript プロジェクトに ESLint v9Prettier を合わせて導入する機会があったので、その手順をまとめてみます。

ちなみにこの手順では ESLint の新規導入を前提にしています。v8 以前からの移行については以下を参照してください。

https://eslint.org/docs/latest/use/migrate-to-9.0.0

やってみた

開発環境は以下の通りです。

バージョン
Node.js 22.17.1
npm 10.9.0
TypeScript 5.7.2
VS Code 1.102.3

パッケージインストール

まずは ESLint と Prettier のパッケージの最新版をインストールします。

npm install --save-dev eslint prettier

加えて ESLint での設定を補助するためのパッケージ(プラグイン)もインストールします。

npm install --save-dev \
  @typescript-eslint/eslint-plugin \
  @typescript-eslint/parser \
  eslint-config-prettier \
  eslint-plugin-import

上記プラグインより ESLint デフォルトのルールだけでは実現できない以下の機能が追加されます。

  • ESLint v9 と Prettier の併用のサポート
  • TypeScript のサポート
  • import/export 構文の検証

インストールされた各パッケージのバージョンは以下の通りです。

パッケージ名 バージョン
eslint 9.32.0
prettier 3.6.2
@typescript-eslint/eslint-plugin 8.38.0
@typescript-eslint/parser 8.38.0
eslint-config-prettier 10.1.8
eslint-plugin-import 2.32.0

ルールの設定

ESLint と Prettier のルールを設定するための設定ファイルを作成します。

ESLint

Flat Config 形式の ESLint 設定ファイルを eslint.config.js として作成します。

eslint.config.js
import tseslint from "@typescript-eslint/eslint-plugin";
import tsParser from "@typescript-eslint/parser";
import eslintConfigPrettier from "eslint-config-prettier";
import importPlugin from "eslint-plugin-import";

/**
 * ESLint 設定ファイル
 *
 * MEMO: 記述の簡略化のため、defineConfig() を使用せず配列を直接エクスポートしている
 */
export default [
  /**
   * チェック無視対象のグローバル設定
   * @see https://eslint.org/docs/latest/use/configure/configuration-files#globally-ignoring-files-with-ignores
   */
  {
    ignores: ["**/cdk.out/"], // AWS CDK プロジェクトの場合、出力ディレクトリを無視
  },

  /**
   * Prettier と競合する ESLint ルールを無効化
   * @see https://github.com/prettier/eslint-config-prettier?tab=readme-ov-file#eslintconfigjs-flat-config-plugin-caveat
   */
  eslintConfigPrettier,

  /**
   * メインの ESLint 設定(TS/JS 共通)
   */
  {
    /**
     * チェック対象のファイルパターンのグローバル設定。TypeScript と JavaScript の両方を対象とする
     * @see https://eslint.org/docs/latest/use/configure/configuration-files#specifying-files-and-ignores
     */
    files: ["**/*.ts", "**/*.js"], // 必要に応じて jsx や tsx を追加

    /**
     * ESLint のパーサーを typescript-eslint を使用して TypeScript 用に設定
     * @see https://eslint.org/docs/latest/extend/custom-parsers#packaging-a-custom-parser
     */
    languageOptions: {
      parser: tsParser,
    },

    /**
     * 使用するプラグイン一覧
     */
    plugins: {
      import: importPlugin, // import/export 構文の検証
      "@typescript-eslint": tseslint, // TypeScript 専用ルール
    },

    /**
     * 各ルールの設定
     */
    rules: {
      // import 文をアルファベット順にソート
      "import/order": [
        "error",
        {
          alphabetize: { order: "asc" },
        },
      ],

      /**
       * 未使用の変数/引数をエラーに
       * @see https://typescript-eslint.io/rules/no-unused-vars/#how-to-use
       *
       * MEMO: ESLint のデフォルトルールは enum などの特定のケースで誤検出することがあるため、@typescript-eslint のルールを使用
       */
      "@typescript-eslint/no-unused-vars": "error",
      "no-unused-vars": "off", // デフォルトルールは競合回避のため無効化

      /**
       * コールバックを必ずアロー関数で書く
       * @see https://eslint.org/docs/latest/rules/prefer-arrow-callback
       */
      "prefer-arrow-callback": "error",
    },
  },
];

ここで、Flat Config の rules プロパティでは、プラグインで追加したルールや、ESLint でデフォルトで使用できる各ルールを設定できます。デフォルトルール一覧は以下にあります。

https://eslint.org/docs/latest/rules/

使い方としては、ドキュメントでは定義済みルールセットである js/recommended を使用し、その上で必要に応じてデフォルトルール毎の設定を上書きします。JS のみのプロジェクトであれば js/recommended を使用するのが簡単です。

しかし今回は TS プロジェクトであるため、外部プラグインである typescript-eslint を使用して TypeScript 向けの推奨ルールセットを適用し、その上で個別のルールの設定を行っています。

またドキュメントでは defineConfig() を使用して Flat Config を記述する方法が紹介されていますが、今回は typescript-eslint を使う上での設定の簡略化のために defineConfig() を使わずに配列を直接エクスポートしています。
https://eslint.org/docs/latest/use/configure/configuration-files

Prettier

Prettier の設定ファイルを .prettierrc.json として作成します。

今回はデフォルトの設定を使用するため空の設定ファイルを作成します。これにより Prettier のルールがデフォルト値で適用されます。特段の要件が無い限り、デフォルト設定で十分でしょう。

.prettierrc.json
{}

ここで、デフォルト設定にもかかわらず空の設定ファイルを作成する理由は、VS Code ワークスペースなど上位の Prettier の設定でプロジェクト毎の設定が上書きされないようにするためです。よって必須では無いですが、プロジェクトの一貫性を保つために作成しておくことをおすすめします。

また、もし個別のルールをカスタマイズしたい場合は、以下を参考にしてください。

https://prettier.io/docs/options

ファイル ignore 設定

ESLint および Prettier のチェックで、不必要な検知を回避したり、チェック実行速度の向上のために 適切なファイル ignore 設定を行いましょう。

ESLint

ドキュメントでは defineConfig() を使って Flat Config を記述する場合に globalIgnores() を使う方法が紹介されています。

https://eslint.org/docs/latest/use/configure/ignore

しかし今回は defineConfig() を使わずに設定しているため、ignores プロパティを使用してグローバルな ignore 設定を行ってます。

eslint.config.js
{
  ignores: ["**/cdk.out/"], // AWS CDK プロジェクトの場合、出力ディレクトリを無視
}

https://eslint.org/docs/latest/use/configure/configuration-files#globally-ignoring-files-with-ignores

また ESLint では、node_modules/ および .git/ 配下のファイルはデフォルトで ignore されるので、これらは設定する必要はありません。

This configuration specifies that all of the files in the .config directory should be ignored. This pattern is added after the default patterns, which are ["**/node_modules/", ".git/"].

Prettier

Prettier では .gitignore で指定されているパスと node_modules はデフォルトで無視されますが、特定のパスを ignore したい場合は .prettierignore ファイルを作成して指定します。

https://prettier.io/docs/cli.html#--ignore-path

今回は AWS CDK プロジェクトを想定して、CDK の出力ディレクトリ cdk.out を無視する設定を追加しています。

.prettierignore
**/cdk.out

キャッシュ利用

一度チェックしたファイルを再度チェックする際に、キャッシュを利用することでチェック速度を向上させることができます。

ESLint

ESLint ではコマンドに --cache オプションを付けます。

https://eslint.org/docs/latest/use/command-line-interface#caching

キャッシュは .eslintcache というファイル名でプロジェクトルートに保存されます。こちらのファイルは Git で管理しないように .gitignore に追加します。

.gitignore
.eslintcache

Prettier

Prettier でも同様にコマンドに --cache オプションを付けます。

https://prettier.io/docs/cli#--cache

ただし ESLint とは異なりキャッシュは node_modules/.cache/prettier/.prettier-cache に保存されるため、特に .gitignore に追加する必要はありません。

npm スクリプト

ESLint と Prettier のチェックを簡単に実行できるように、package.json に npm スクリプトを追加します。

package.json
{
  "scripts": {
    "check:lint": "eslint --cache --max-warnings=0",
    "check:format": "prettier --check --cache \"./packages/**/*.{js,ts}\""
  }
}

ESLint

check:lint スクリプトで実行する ESLint コマンドです。

"check:lint": "eslint --cache --max-warnings=0",

--cache オプションを使用してキャッシュを有効にし、--max-warnings=0 オプションで警告(warn)があれば必ずエラー(error)として扱い Nonzero Exit Code を返すようにしています。

https://eslint.org/docs/latest/use/command-line-interface#--max-warnings

warn および error は ESLint のルールの重大度を指しており、前述の eslint.config.jsrules セクションでもルールごとの重大度を制御する記載をしています。

https://eslint.org/docs/latest/use/configure/rules#rule-severities

ESLint の新規導入や大きなアップデートを行い warn が多数発生して解消に時間が掛かるなどで無い限り、--max-warnings=0 を指定して warn をエラーとして扱うのが良いでしょう。

Prettier

check:format スクリプトで実行する Prettier コマンドです。

"check:format": "prettier --check --cache \"**/*.{js,ts}\""

--check オプションを使用して、フォーマットが適用されていないファイルを検出します。--cache オプションでキャッシュを有効にし、"**/*.{js,ts}" で対象のファイルパターンを指定しています。拡張子は必要に応じて jsxtsx を追加してください。

ES Module 対応

TypeScript プロジェクトが ES Module を使用している場合、ESLint に対してそれを明示するために package.json"type": "module" を追加します。

package.json
{
  "type": "module"
}

eslint.config.js ファイルが ES Module の構文を使用しているにも関わらず、上記が設定されていない場合、ESLint を実行すると以下のような Warning が出力されます。

設定しない場合に出力される Warning
$ npm run check:lint

> icasu-cdk-serverless-api-sample@0.0.0-github-release check:lint
> eslint --cache --max-warnings=0

(node:99777) [MODULE_TYPELESS_PACKAGE_JSON] Warning: Module type of file:///Users/wakatsuki.ryuta/projects/cm-rwakatsuki/icasu-cdk-serverless-api-sample/eslint.config.js?mtime=1754193887752 is not specified and it doesn't parse as CommonJS.
Reparsing as ES module because module syntax was detected. This incurs a performance overhead.
To eliminate this warning, add "type": "module" to /Users/wakatsuki.ryuta/projects/cm-rwakatsuki/icasu-cdk-serverless-api-sample/package.json.
(Use `node --trace-warnings ...` to show where the warning was created)

CI

CI ワークフローを実装している場合は、ESLint と Prettier のチェックも実行するように設定しましょう。下記は GitHub Actions の例です。

.github/workflows/ci.yml
name: CI

on:
  pull_request

jobs:
  Integration:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node 22
        uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Cache Dependency
        uses: actions/cache@v4
        id: cache_dependency
        env:
          cache-name: cache-dependency
        with:
          path: "**/node_modules"
          key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('package-lock.json') }}

      - name: Install Dependency
        if: ${{ steps.cache_dependency.outputs.cache-hit != 'true' }}
        run: npm ci

      # Prettier によるコードフォーマットチェック
      - name: Check Format
        run: npm run check:format

      # ESLint によるコード品質チェック
      - name: Check Lint
        run: npm run check:lint

VS Code 設定

VS Code で ESLint と Prettier を使用するための設定を行います。

.vscode/extensions.json を次のように設定して、ESLint と Prettier の拡張機能のインストールが推奨されるようにします。

.vscode/extensions.json
{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode"
  ]
}

下記が導入されることにより、VS Code 上で自動フォーマットやインラインでの警告表示が行われるようになります。

https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint

https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode

例えば import 構文の順序が ESLint のルールに違反している場合、VS Code 上で次のような警告が表示されます。

また Prettier の自動フォーマットを有効にするためには、.vscode/settings.json を次のように設定します。

.vscode/settings.json
{
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "editor.formatOnSave": true
}

これにより、TypeScript および JavaScript ファイルを保存する際に自動的に Trailing Comma 追加やインデントの調整などが行われるようになります。

まとめ

今回の手順で、TypeScript プロジェクトに ESLint v9 と Prettier を導入することができました。参考までに、設定対象となったファイルの構成は以下のようになります。

.
├── .gitignore
├── .prettierignore
├── .prettierrc.json
├── .github
│   └── workflows
│       └── ci.yml
├── .vscode
│   ├── extensions.json
│   └── settings.json
├── eslint.config.js
├── package-lock.json
└── package.json

リンターおよびフォーマッターを導入することで、コードの品質を保ちながら開発を進めることができ、またチーム内でのコードスタイルの統一も図ることができます。活用していきましょう。

以上

この記事をシェアする

facebookのロゴhatenaのロゴtwitterのロゴ

© Classmethod, Inc. All rights reserved.