ESLint の使い方完全ガイド — JavaScript/TypeScript の静的解析ツール

一言でいうと

ESLint は、JavaScript/TypeScript コードを AST（抽象構文木）ベースで静的解析し、バグの原因となるパターンやコーディング規約違反を検出・自動修正するリンターです。完全にプラグイン方式で設計されており、すべてのルールを自由にカスタマイズできます。

どんな時に使う？

• コード品質の統一 — チーム開発で「未使用変数の放置」「var の使用」「=== の不使用」などを機械的に防ぎたいとき
• バグの早期発見 — 到達不能コード、無限ループ、定数同士の不要な比較など、実行前に検出したいとき
• CI/CD パイプラインでのゲートチェック — プルリクエスト時にコード品質を自動検証し、基準を満たさないコードのマージを防ぎたいとき

インストール

前提条件（v10.2.0 時点）: Node.js ^20.19.0、^22.13.0、または >=24 が必要です。

対話形式で初期設定まで一括実行（推奨）

# npm
npm init @eslint/config@latest

# pnpm
pnpm create @eslint/config@latest

# yarn
yarn create @eslint/config@latest

手動インストール

# npm
npm install --save-dev eslint

# yarn
yarn add --dev eslint

# pnpm
pnpm add --save-dev eslint

pnpm を使う場合の注意: .npmrc に以下を追加することが推奨されています。

auto-install-peers=true
node-linker=hoisted

基本的な使い方

1. 設定ファイルの作成

ESLint v9 以降では Flat Config（eslint.config.js）が標準です。defineConfig ヘルパーを使うと型補完が効きます。

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
  {
    files: ["**/*.js", "**/*.ts", "**/*.mjs"],
    rules: {
      "prefer-const": "warn",
      "no-constant-binary-expression": "error",
      "no-unused-vars": "warn",
    },
  },
]);

2. 実行

# 特定ファイルを検査
npx eslint src/index.ts

# ディレクトリ全体を検査
npx eslint src/

# 自動修正可能なものを修正
npx eslint src/ --fix

3. package.json にスクリプトを追加

{
  "scripts": {
    "lint": "eslint src/",
    "lint:fix": "eslint src/ --fix"
  }
}

よく使う API・設定パターン

1. ルールの重大度設定

ルールには3段階の重大度を設定できます。

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
  {
    files: ["**/*.js", "**/*.ts"],
    rules: {
      "no-console": "off",       // 0: ルール無効
      "no-debugger": "warn",     // 1: 警告（終了コードに影響しない）
      "no-eval": "error",        // 2: エラー（終了コード 1）
    },
  },
]);

2. プラグインの導入（TypeScript ESLint の例）

npm install --save-dev typescript-eslint

// eslint.config.js
import { defineConfig } from "eslint/config";
import tseslint from "typescript-eslint";

export default defineConfig([
  ...tseslint.configs.recommended,
  {
    files: ["**/*.ts", "**/*.tsx"],
    rules: {
      "@typescript-eslint/no-explicit-any": "warn",
      "@typescript-eslint/no-unused-vars": ["error", {
        argsIgnorePattern: "^_",
      }],
    },
  },
]);

3. ファイル・ディレクトリの除外（ignores）

// eslint.config.js
import { defineConfig } from "eslint/config";

export default defineConfig([
  {
    ignores: [
      "dist/",
      "node_modules/",
      "*.config.js",
      "**/*.generated.ts",
    ],
  },
  {
    files: ["**/*.ts"],
    rules: {
      "prefer-const": "error",
    },
  },
]);

4. 言語オプション（ECMAScript バージョン・グローバル変数）

// eslint.config.js
import { defineConfig } from "eslint/config";
import globals from "globals";

export default defineConfig([
  {
    files: ["**/*.js"],
    languageOptions: {
      ecmaVersion: 2025,
      sourceType: "module",
      globals: {
        ...globals.browser,
        ...globals.node,
      },
    },
    rules: {
      "no-undef": "error",
    },
  },
]);

5. Node.js API によるプログラマティック実行

// lint-runner.ts
import { ESLint } from "eslint";

async function main() {
  const eslint = new ESLint({
    fix: true,
  });

  // ファイルを検査
  const results = await eslint.lintFiles(["src/**/*.ts"]);

  // 自動修正を書き込み
  await ESLint.outputFixes(results);

  // 結果をフォーマットして出力
  const formatter = await eslint.loadFormatter("stylish");
  const resultText = await formatter.format(results);

  console.log(resultText);

  // エラーがあれば終了コード 1
  const hasErrors = results.some((r) => r.errorCount > 0);
  if (hasErrors) {
    process.exit(1);
  }
}

main();

類似パッケージとの比較

選定の指針: エコシステムの豊富さ・カスタマイズ性を重視するなら ESLint、速度を最優先するなら Biome や oxlint が有力です。大規模プロジェクトでは ESLint + oxlint の併用も増えています。

注意点・Tips

Flat Config への移行

ESLint v9 以降、.eslintrc.* 形式（Legacy Config）は非推奨となり、eslint.config.js（Flat Config）が標準です。v10 では Legacy Config のサポートが完全に削除されています。旧形式を使っている場合は Migration Guide を参照してください。

Prettier との棲み分け

ESLint はリンター（コード品質チェック）、Prettier はフォーマッター（コード整形）です。両者は競合するものではなく併用が推奨されます。フォーマット系のルール（indent, semi など）は ESLint 側で無効化し、Prettier に任せるのがベストプラクティスです。

npm install --save-dev eslint-config-prettier

// eslint.config.js
import { defineConfig } from "eslint/config";
import prettier from "eslint-config-prettier";

export default defineConfig([
  // ... 他の設定
  prettier, // 最後に配置してフォーマット系ルールを無効化
]);

JSX サポートの注意

ESLint は JSX 構文のパースをネイティブサポートしていますが、React 固有のセマンティクス（Hooks のルールなど）は理解しません。React プロジェクトでは eslint-plugin-react と eslint-plugin-react-hooks を別途導入してください。

インラインでのルール無効化

特定の行だけルールを無効化したい場合：

// eslint-disable-next-line no-console
console.log("デバッグ用の一時的な出力");

/* eslint-disable @typescript-eslint/no-explicit-any */
// このブロック内では any を許容
const legacyData: any = fetchLegacyAPI();
/* eslint-enable @typescript-eslint/no-explicit-any */

Tip: eslint-disable の乱用はリンターの意味を失わせます。--report-unused-disable-directives オプションで不要な disable コメントを検出できます。

パフォーマンス改善

大規模プロジェクトで実行が遅い場合：

# どのルールに時間がかかっているか確認
TIMING=1 npx eslint src/

# キャッシュを有効化（2回目以降が高速に）
npx eslint src/ --cache --cache-location .eslintcache

まとめ

ESLint は JavaScript/TypeScript エコシステムにおける静的解析のデファクトスタンダードであり、10年以上の実績と圧倒的なプラグインエコシステムを持ちます。v10 では Flat Config が完全に標準化され、defineConfig による型安全な設定が可能になりました。Biome や oxlint など高速な代替ツールも台頭していますが、ルールの豊富さと拡張性において ESLint は依然として最も柔軟な選択肢です。