shared-tooling-eslint-prettier

ESLint & Prettier

クイックガイド： defineConfig() と globalIgnores() を使用した ESLint 9 以降のフラット設定。projectService: true を使用した typescript-eslint v8 以降。書式を統一する Prettier の共有設定。競合するルールを無効にする eslint-config-prettier。より快適な開発体験のための eslint-plugin-only-warn。

警告：ESLint 10 は 2026 年 2 月にリリースされ、.eslintrc のサポートが完全に削除されます。今すぐフラット設定に移行してください。

---

<critical_requirements>

重要：このスキルを使用する前に

（eslint/config の defineConfig() を使用した ESLint 9 以降のフラット設定を必ず使用してください。レガシーな .eslintrc は使用しないでください）

（明示的なグローバル除外パターンには必ず globalIgnores() を使用してください。ignores プロパティだけを指定する方法は使用しないでください）

（型情報を利用した lint には、projectService: true を使用する typescript-eslint v8 以降を必ず使用してください）

（エラーを警告に変換して開発体験を向上させるため、eslint-plugin-only-warn を必ず含めてください）

（Prettier と競合する書式ルールを無効にするため、eslint-config-prettier を必ず使用してください）

</critical_requirements>

---

自動検出： ESLint 9 のフラット設定、defineConfig、globalIgnores、eslint.config.ts、Prettier 設定、prettier.config.mjs、eslint-config-prettier、eslint-plugin-only-warn、typescript-eslint の projectService、.eslintrc からの移行

使用する場面：

• ESLint 9／10 のフラット設定（単独または共有）をセットアップする
• Prettier を共有設定で構成する
• レガシーな .eslintrc からフラット設定に移行する
• ESLint と Prettier を統合する（eslint-config-prettier）
• typescript-eslint v8 以降を projectService で構成する
• カスタム ESLint ルール（名前付きエクスポート、インポート制限、型のインポート）を設定する

使用しない場面：

• 実行時のコード（これはビルド時のツール専用です）
• CI/CD パイプラインの設定
• Git フックや lint-staged のセットアップ
• TypeScript コンパイラーの設定（tsconfig）
• バンドラーの設定

詳細なリソース：

• examples/core.md - フラット設定と Prettier の基本セットアップ
• examples/eslint.md - 高度な ESLint パターン（共有設定、カスタムルール、ESLint 10 への移行）
• examples/prettier.md - 高度な Prettier パターン（TS 設定、実験的オプション、除外ファイル）
• reference.md - バージョン情報と公式ドキュメントへのリンク

---

方針

リントと書式設定は、高速で一貫性があり、作業を妨げないものであるべきです。開発者がツールと格闘するのではなく、ツールが開発の妨げにならずに問題を早期に検出できるようにするべきです。

基本原則：

1. エラーではなく警告 - only-warn を使って lint エラーを警告に変換し、開発者が作業を止められることなく反復できるようにします
2. 信頼できる唯一の情報源 - 共有設定によって、パッケージ間やチームメンバー間で設定に差異が生じるのを防ぎます
3. 書式設定を自動化 - 書式設定はすべて Prettier が担当し、ESLint はコード品質のみを担当します
4. 競合なし - eslint-config-prettier により、ESLint と Prettier の設定が食い違わないようにします

---

基本パターン

パターン 1：defineConfig() を使った ESLint 9 以降のフラット設定

ESLint 9 以降ではフラット設定を使用します。eslint/config の defineConfig() ヘルパーは、型安全性と配列の自動フラット化を提供します。globalIgnores() を使うと、グローバルな除外パターンを明示できます。

// eslint.config.ts — the essential flat config
import js from "@eslint/js";
import { defineConfig, globalIgnores } from "eslint/config";
import tseslint from "typescript-eslint";
import eslintConfigPrettier from "eslint-config-prettier";
import * as onlyWarnPlugin from "eslint-plugin-only-warn";

export default defineConfig(
  globalIgnores(["dist/**", "generated/**", "node_modules/**"]),
  js.configs.recommended,
  eslintConfigPrettier,
  tseslint.configs.recommended,
  { plugins: { "only-warn": onlyWarnPlugin } }, // must be last
);

要点： defineConfig() は配列を自動的にフラット化するため、スプレッド演算子は不要です。globalIgnores() を使うことで、ignores だけを指定した場合に生じる挙動の曖昧さを防げます。only-warn は、それより前に指定されたすべてのエラーを警告に変換します。eslint-config-prettier は、Prettier と競合する書式ルールを無効にします。

単独設定と共有設定の完全なパターンについては、examples/core.md を参照してください。

---

### パターン 2：projectService を使用した typescript-eslint v8+

projectService 機能（v8 で安定版）は、各ファイルに最も近い tsconfig.json を自動検出し、脆弱な手動の project パス設定を置き換えます。

parserOptions: {
  projectService: true,
  allowDefaultProject: ["*.config.ts", "*.config.mjs"],
},

主なポイント： tsconfig.eslint.json ファイルが不要になります。手動でのプロジェクト設定より高速で、allowDefaultProject により tsconfig に含まれない設定ファイルにも対応できます。

typescript-eslint の設定全体については、examples/core.md を参照してください。

---

パターン 3：共有設定パターン（モノレポ／チーム）

チームやモノレポでは、設定の不整合を防ぐために、Lint 設定を共有パッケージに切り出します。

// packages/eslint-config/base.ts — shared config
export const baseConfig = defineConfig(
  globalIgnores(["dist/**", "generated/**"]),
  js.configs.recommended,
  eslintConfigPrettier,
  tseslint.configs.recommended,
  { plugins: { "only-warn": onlyWarnPlugin } },
);

// apps/my-app/eslint.config.ts — consuming shared config
export default defineConfig(baseConfig, customRules, {
  rules: { "no-console": "warn" },
});

主なポイント： defineConfig() が自動的にフラット化するため、スプレッド構文は不要です。単一の信頼できる情報源によって設定の不整合を防ぎ、TypeScript の設定ファイルで型チェックを行えます。

共有設定とカスタムルールのパターンについては、examples/eslint.md を参照してください。

---

パターン 4：Prettier の共有設定

Prettier の設定は、すべてのパッケージで統一する必要があります。チームでは共有設定を使用してください。

// prettier.config.mjs
const config = {
  printWidth: 100,
  semi: true,
  singleQuote: false,
  bracketSpacing: true,
  arrowParens: "always",
  endOfLine: "lf",
  bracketSameLine: false,
  // trailingComma: "all" is the default in Prettier 3.0+
};
export default config;

主なポイント： v3.0 以降では trailingComma: "all" がデフォルトです（明示的に設定する必要はありません）。bracketSameLine は非推奨の jsxBracketSameLine に代わる設定です。明示的に endOfLine: "lf" を指定すると、クロスプラットフォームの問題を防げます。

TypeScript の設定ファイル、実験的なオプション、無視パターンについては、examples/prettier.md を参照してください。

---

パターン 5：カスタム ESLint ルール

プロジェクトの規約を適用するための一般的なカスタムルールです。名前付きエクスポート、一貫した型インポート、未使用変数の検出、インポート境界の適用などが含まれます。

export const customRules = {
  rules: {
    "import/no-default-export": "warn",
    "@typescript-eslint/consistent-type-imports": [
      "warn",
      { prefer: "type-imports" },
    ],
    "@typescript-eslint/no-unused-vars": [
      "warn",
      { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
    ],
  },
};

インポート境界の制限を含むカスタムルールのパターン全体については、examples/eslint.md を参照してください。

---

パターン 6：extends プロパティの使用（ESLint 9.15+）

フラット設定オブジェクトの extends プロパティを使うと、プラグインの組み合わせが簡単になります。プラグインの形式（オブジェクト、配列、文字列）にかかわらず、設定のマージ方法を標準化できます。

export default defineConfig({
  files: ["**/*.ts", "**/*.tsx"],
  extends: [
    "eslint/recommended",
    tseslint.configs.recommended,
    // Add your framework plugin's flat config here
  ],
  rules: { "no-console": "warn" },
});

extends パターン全体については、examples/core.md を参照してください。

---

<decision_framework>

選択の指針

ESLint + Prettier と代替手段の比較

Need linting and formatting?
├─ Speed is critical bottleneck (1000+ files)?
│   └─ YES → Consider a Rust-based unified linter/formatter (not this skill's scope)
└─ Need mature plugin ecosystem?
    └─ YES → ESLint 9/10 + Prettier ✓

ESLint + Prettier の強み： 成熟したエコシステム、豊富なプラグインサポート、フレームワーク固有のプラグイン

ESLint 9 と ESLint 10 の比較

Which ESLint version?
├─ New project?
│   └─ ESLint 10 (latest, cleanest API)
├─ Existing project with flat config?
│   └─ ESLint 10 (straightforward upgrade)
├─ Existing project with .eslintrc?
│   ├─ Can invest time to migrate?
│   │   └─ YES → Migrate to flat config, then ESLint 10
│   └─ NO → ESLint 9.x (still supported, but plan migration)
└─ Node.js < 20.19.0?
    └─ ESLint 9.x (ESLint 10 requires 20.19.0+)

共有設定とローカル設定の比較

Setting up linting/formatting?
├─ Monorepo with multiple packages?
│   └─ YES → Shared config ✓
├─ Team project (2+ developers)?
│   └─ YES → Shared config (consistency matters)
└─ Single package / solo project?
    └─ YES → Local config is fine

Prettier の設定ファイル形式

What Prettier config format to use?
├─ Need type checking in config?
│   ├─ Node.js 22.6.0+? → prettier.config.ts
│   └─ NO → Use .mjs with JSDoc types
├─ ESM project? → prettier.config.mjs
└─ CommonJS project? → prettier.config.cjs

</decision_framework>

---

<red_flags>

重大な問題

優先度の高い問題：

• ❌ ESLint 9+ のフラット設定ではなく、従来の .eslintrc 形式を使用している（ESLint 10 では動作しません）
• ❌ globalIgnores() ヘルパーではなく、単独の ignores プロパティを使用している（動作が曖昧です。単独ではグローバルな無視として機能しますが、ほかのプロパティと併用するとローカルな除外として機能します）
• ❌ eslint-plugin-only-warn がない（エラーによって開発中の作業が妨げられます）
• ❌ eslint-config-prettier がない（ESLint と Prettier のルールが競合し、延々と修正を繰り返すことになります）

優先度が中程度の問題：

• ⚠️ typescript-eslint で projectService: true ではなく、手動で project オプションを使用している（モノレポでは不安定で、処理も遅くなります）
• ⚠️ Prettier で非推奨の jsxBracketSameLine オプションを使用している（Prettier 2.4 で bracketSameLine に改名されました）
• ⚠️ Prettier 3.0+ で trailingComma: "all" を明示的に設定している（すでにデフォルトです）
• ⚠️ tseslint.config() ラッパーを使用している（ESLint のネイティブな defineConfig() を優先するため、非推奨化が予定されています）
• ⚠️ 共通設定ではなく、各パッケージに設定値をハードコードしている

注意点とエッジケース：

• only-warn プラグインは、ほかのプラグインのエラーを警告に変換するため、ほかのプラグインの後に読み込む必要があります
• defineConfig() は配列を自動的にフラット化するため、スプレッド演算子は決して使用しないでください
• projectService には typescript-eslint v8+ が必要です（v6-v7 では EXPERIMENTAL_useProjectService でした）
• ESLint 10 には Node.js ^20.19.0 || ^22.13.0 || >=24 が必要です（v21.x と v23.x は明示的にサポート対象外です）
• ESLint 10 では設定の検索が cwd ではなく、リント対象ファイルのディレクトリから始まります。これにより、モノレポで複数の設定を使用できます
• Prettier の TypeScript 設定ファイル（.prettierrc.ts）には Node.js 22.6.0+ が必要です。Node v24.3.0 より前では、--experimental-strip-types を指定して実行してください
• Prettier 3.0+ の API は非同期です。同期 API を使用するプラグインは移行が必要です（同期ラッパーには @prettier/sync を使用してください）
• ESLint 9.15+：eslint.config.ts の TypeScript 設定ファイルと extends プロパティがネイティブにサポートされています
• ESLint 9.34+：--concurrency フラグでマルチスレッドのリントを利用できます（大規模プロジェクトでパフォーマンスが 30～300％向上します）
• ESLint 10：/* eslint-env */ コメントでエラーが発生するようになり、非推奨の Linter メソッドは削除されました

</red_flags>

---

<critical_reminders>

重要な注意事項

（eslint/config の defineConfig() を使った ESLint 9+ のフラット設定を必ず使用してください。従来の .eslintrc は使用しないでください）

（明示的なグローバル無視パターンには必ず globalIgnores() を使用してください。単独の ignores プロパティは使用しないでください）

（型情報を使ったリントには、projectService: true を指定した typescript-eslint v8+ を必ず使用してください）

（開発者体験を向上させるため、エラーを警告に変換する eslint-plugin-only-warn を必ず含めてください）

（Prettier と競合するフォーマットルールを無効にするため、eslint-config-prettier を必ず使用してください）

これらのルールに従わないと、ツールの動作が一貫しなくなり、フォーマットルールが競合し、開発者の作業が妨げられます。

警告：ESLint 10（2026年2月）は .eslintrc のサポートを完全に削除します。今すぐ移行を計画してください。

</critical_reminders>