
TypeScript プロジェクトに ESLint v9 + Prettier を導入する
こんにちは、製造ビジネステクノロジー部の若槻です。
昨年4月に ESLint v9 がリリースされました。v9 では、ESLint の設定ファイルの形式が大きく変更され、これまでの .eslintrc.js
や .eslintrc.json
から eslint.config.js
という新しい形式(Flat Config)に移行することが推奨されています。
今回は、TypeScript プロジェクトに ESLint v9 と Prettier を合わせて導入する機会があったので、その手順をまとめてみます。
ちなみにこの手順では ESLint の新規導入を前提にしています。v8 以前からの移行については以下を参照してください。
やってみた
開発環境は以下の通りです。
バージョン | |
---|---|
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
として作成します。
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 でデフォルトで使用できる各ルールを設定できます。デフォルトルール一覧は以下にあります。
使い方としては、ドキュメントでは定義済みルールセットである js/recommended
を使用し、その上で必要に応じてデフォルトルール毎の設定を上書きします。JS のみのプロジェクトであれば js/recommended
を使用するのが簡単です。
しかし今回は TS プロジェクトであるため、外部プラグインである typescript-eslint を使用して TypeScript 向けの推奨ルールセットを適用し、その上で個別のルールの設定を行っています。
またドキュメントでは defineConfig()
を使用して Flat Config を記述する方法が紹介されていますが、今回は typescript-eslint を使う上での設定の簡略化のために defineConfig()
を使わずに配列を直接エクスポートしています。
Prettier
Prettier の設定ファイルを .prettierrc.json
として作成します。
今回はデフォルトの設定を使用するため空の設定ファイルを作成します。これにより Prettier のルールがデフォルト値で適用されます。特段の要件が無い限り、デフォルト設定で十分でしょう。
{}
ここで、デフォルト設定にもかかわらず空の設定ファイルを作成する理由は、VS Code ワークスペースなど上位の Prettier の設定でプロジェクト毎の設定が上書きされないようにするためです。よって必須では無いですが、プロジェクトの一貫性を保つために作成しておくことをおすすめします。
また、もし個別のルールをカスタマイズしたい場合は、以下を参考にしてください。
ファイル ignore 設定
ESLint および Prettier のチェックで、不必要な検知を回避したり、チェック実行速度の向上のために 適切なファイル ignore 設定を行いましょう。
ESLint
ドキュメントでは defineConfig()
を使って Flat Config を記述する場合に globalIgnores()
を使う方法が紹介されています。
しかし今回は defineConfig()
を使わずに設定しているため、ignores
プロパティを使用してグローバルな ignore 設定を行ってます。
{
ignores: ["**/cdk.out/"], // AWS CDK プロジェクトの場合、出力ディレクトリを無視
}
また 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
ファイルを作成して指定します。
今回は AWS CDK プロジェクトを想定して、CDK の出力ディレクトリ cdk.out
を無視する設定を追加しています。
**/cdk.out
キャッシュ利用
一度チェックしたファイルを再度チェックする際に、キャッシュを利用することでチェック速度を向上させることができます。
ESLint
ESLint ではコマンドに --cache
オプションを付けます。
キャッシュは .eslintcache
というファイル名でプロジェクトルートに保存されます。こちらのファイルは Git で管理しないように .gitignore
に追加します。
.eslintcache
Prettier
Prettier でも同様にコマンドに --cache
オプションを付けます。
ただし ESLint とは異なりキャッシュは node_modules/.cache/prettier/.prettier-cache
に保存されるため、特に .gitignore
に追加する必要はありません。
npm スクリプト
ESLint と Prettier のチェックを簡単に実行できるように、package.json
に npm スクリプトを追加します。
{
"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 を返すようにしています。
warn
および error
は ESLint のルールの重大度を指しており、前述の eslint.config.js
の rules
セクションでもルールごとの重大度を制御する記載をしています。
ESLint の新規導入や大きなアップデートを行い warn が多数発生して解消に時間が掛かるなどで無い限り、--max-warnings=0
を指定して warn をエラーとして扱うのが良いでしょう。
Prettier
check:format
スクリプトで実行する Prettier コマンドです。
"check:format": "prettier --check --cache \"**/*.{js,ts}\""
--check
オプションを使用して、フォーマットが適用されていないファイルを検出します。--cache
オプションでキャッシュを有効にし、"**/*.{js,ts}"
で対象のファイルパターンを指定しています。拡張子は必要に応じて jsx
や tsx
を追加してください。
ES Module 対応
TypeScript プロジェクトが ES Module を使用している場合、ESLint に対してそれを明示するために package.json
に "type": "module"
を追加します。
{
"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 の例です。
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 の拡張機能のインストールが推奨されるようにします。
{
"recommendations": [
"dbaeumer.vscode-eslint",
"esbenp.prettier-vscode"
]
}
下記が導入されることにより、VS Code 上で自動フォーマットやインラインでの警告表示が行われるようになります。
例えば import 構文の順序が ESLint のルールに違反している場合、VS Code 上で次のような警告が表示されます。
また Prettier の自動フォーマットを有効にするためには、.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
リンターおよびフォーマッターを導入することで、コードの品質を保ちながら開発を進めることができ、またチーム内でのコードスタイルの統一も図ることができます。活用していきましょう。
以上