Prettier設定の.prettierrcとESLint競合回避を最短で固める

レビューを開こうとしたら、PRの差分が900行ありました。中身を読んでいくと、実際に直っていたのは3行。残りはぜんぶ、インデントと引用符と末尾カンマの揺れでした。

しかも犯人は僕です。エディタのデフォルト整形が勝手に走って、触ってもいないファイルまで「きれいに」してしまっていた。レビュアーには平謝りして、その日のうちにPrettierを入れ直しました。

フォーマットの揺れは、放っておくと毎回こういう形で時間を奪っていきます。一人で書いているうちは気にならないのに、Claude Codeに実装を任せたり、チームで触り始めたりした瞬間に表面化する。今日はその対策を、設定ファイルの中身からESLintとの仲直りまで、順番に固めていきます。

この記事の要点

• Prettierは「見た目だけ」を機械的にそろえるフォーマッタ。バグや品質のルールはESLintの担当で、役割を混ぜると必ず衝突する。
• .prettierrcに書くのは少数のルールだけ。printWidthやendOfLineなど、揺れやすい数項目を決めれば残りは任せられる。
• ESLintを併用しているならeslint-config-prettierを入れて、フォーマット系ルールを一括で黙らせる。これが競合回避の核心。
• 保存時整形（エディタ）、format:check（手元とCI）の二段構えで、フォーマット漏れを人間の目に頼らず止める。
• コミット直前に差分だけ整形したい場合は、husky + lint-stagedへ。詳細は別記事に分けた。

Prettierは見た目だけ、ESLintは中身。ここを混ぜない

最初に役割をはっきりさせます。ここが曖昧なまま設定を始めると、あとで必ず痛い目を見ます。

Prettierはフォーマッタです。コードの動きには一切手を出さず、空白・改行・引用符・末尾カンマみたいな「表記」だけを機械的にそろえます。let x=1 を let x = 1; に直す、あれです。意味は変わらない。見た目だけ。

ESLintはリンタです。「使ってない変数があるよ」「ここ、await忘れてない?」みたいに、バグや品質に関わる中身を指摘します。

問題は、ESLintにも昔は見た目を整えるルール（indentやquotesなど）があったことです。これを有効にしたままPrettierを走らせると、両者が同じ行を奪い合います。Prettierが「ここはスペース2つ」と直した直後に、ESLintが「いや4つだ」と怒る。保存するたびに表記が行ったり来たりする地獄が、これです。

だから方針はシンプルにします。見た目はPrettierに全部渡し、ESLintからは見た目のルールを取り上げる。この仲裁役が、後で出てくるeslint-config-prettierです。

Prettierをローカルに固定して入れる

Prettierはグローバルではなく、プロジェクトのdevDependenciesに、しかもバージョンを固定して入れます。公式のPrettier Installも、ローカルインストールと正確なバージョン固定を推奨しています。

理由は、公式の言い方を借りるとこうです。パッチリリースですら整形結果が微妙に変わることがあるので、チーム内でバージョンがずれると、お互いの整形をお互いが上書きし合う。あの900行PRの一因も、これでした。

npm install --save-dev --save-exact prettier

--save-exact を付けると、package.json に ^3.x.x ではなく 3.x.x と固定で書かれます。手元のPC、Claude Codeの実行環境、CI、全部が同じ結果を出すための保険です。

現行はPrettier 3系です。2系から上げると、Markdownの整形やプラグインの読み込み方が一部変わっているので、既存リポジトリをアップグレードするときは「Prettierのバージョンを上げるだけのPR」を単独で作るのが安全です。機能追加の差分と混ぜると、整形差分なのかバグなのか切り分けられなくなります。

入れたら、初回だけ全体を整形します。

npx prettier . --write

このコマンドも、機能追加の差分とは絶対に混ぜないでください。「Prettier導入だけ」のコミットを先に1つ作る。その後のClaude Code作業では差分が小さく保てて、レビューがぐっと楽になります。

.prettierrcに書くのは、揺れやすい数項目だけ

Prettierは設定項目が意図的に少ないツールです。細かい流派を全部表現させるのではなく、「ここだけ決めたら、あとは機械に任せる」という設計になっています。だから.prettierrcは短くていい。

設定ファイルは.prettierrc(JSON)、prettier.config.mjs(JS)、package.jsonのprettierキーなどから選べます。公式のConfiguration Fileによると、Prettierは対象ファイルの場所から上位ディレクトリへ設定を探しに行き、グローバル設定は使いません。つまり設定はリポジトリに置けば全員に効く、ということです。

最初はJSONの.prettierrcが一番読みやすいです。

{
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "semi": true,
  "singleQuote": false,
  "trailingComma": "all",
  "bracketSpacing": true,
  "arrowParens": "always",
  "endOfLine": "lf",
  "overrides": [
    {
      "files": "*.md",
      "options": { "proseWrap": "always" }
    },
    {
      "files": ["*.yml", "*.yaml"],
      "options": { "singleQuote": false }
    }
  ]
}

各項目の意味を、迷いやすいところだけ補足します。

項目	やること	なぜ入れるか
printWidth	1行の目安の桁数	硬い上限ではなく、改行を判断する目安。100で広めにとると無理な折り返しが減る
endOfLine	改行コードをlfに統一	WindowsとMac/Linuxの改行差で差分が汚れるのを防ぐ
trailingComma	末尾カンマを付ける	配列やオブジェクトに1行足したとき、差分が1行で済む
singleQuote	ダブルクオートに統一	チームで揺れがちな引用符を機械で固定
overrides	ファイル種別ごとに上書き	MarkdownだけproseWrapを変える、などの例外を吸収

endOfLine: "lf"は地味ですが効きます。Windowsで作業する人が混ざるチームだと、改行コードの違いだけでファイル全体が差分になることがある。ここを揃えておくだけで、原因不明の巨大差分が一つ消えます。

Tailwind CSSのクラス順を自動で並べ替えたいならprettier-plugin-tailwindcssという選択肢もありますが、最初から入れないこと。プラグインを増やすほど、整形結果が変わったときの原因切り分けが難しくなります。素のPrettierで安定させてから、必要が出た時点で足すのが順番として安全です。

ESLintと併用するならeslint-config-prettierで競合を消す

ここが「Prettier ESLint 競合」で検索してたどり着く人の、いちばん知りたいところだと思います。

ESLintも使っているプロジェクトでは、ESLint側に残っている見た目系ルールがPrettierとぶつかります。これを手で一個ずつ無効化するのは現実的じゃない。そこでeslint-config-prettierを入れます。公式の説明そのままに、これは「Prettierと衝突する、あるいは不要なルールを全部オフにする」ための設定集です。

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

最近のESLintはFlat Config（eslint.config.js）が標準です。Flat Configでは、eslint-config-prettier/flatを設定配列のいちばん最後に置きます。

// eslint.config.js
import js from "@eslint/js";
import tseslint from "typescript-eslint";
import eslintConfigPrettier from "eslint-config-prettier/flat";

export default [
  js.configs.recommended,
  ...tseslint.configs.recommended,
  // 最後に置くのがポイント。前のルールを上書きしてフォーマット系を黙らせる
  eslintConfigPrettier,
];

順番が肝です。eslint-config-prettierは前の設定を上書きする形でルールをオフにするので、配列の末尾に置かないと効きません。先頭に書くと、後ろのプリセットが見た目ルールを復活させてしまいます。

ちゃんと競合が消えたかは、付属のチェッカーで確認できます。

npx eslint-config-prettier eslint.config.js

これを走らせて「No rules that are unnecessary or conflict with Prettier were found.」のようなメッセージが出れば、ESLintとPrettierが喧嘩しない状態です。ESLint側のルールを足したあとは、これを一度回す習慣をつけておくと安心です。

ESLint自体のFlat Config構成をこれから整える人は、Claude CodeでESLint Flat Configを実務向けに整えるに詳しく書いたので、そちらと合わせて読んでください。

package.json scriptsと.prettierignoreをそろえる

人間、Claude Code、CIが同じコマンドを使えるようにします。これで作業の再現性が一気に上がる。

{
  "scripts": {
    "format": "prettier . --write",
    "format:check": "prettier . --check"
  }
}

使い分けはこうです。formatは実際にファイルを書き換える。format:checkは書き換えずに「未整形のファイルがあるか」だけを報告する。普段はnpm run format、CIではnpm run format:check、と覚えれば十分です。

そして、整形してほしくないファイルは.prettierignoreで外します。生成物、ビルド成果物、キャッシュ、ロックファイルなど、人間が読みやすくする必要のないものです。

node_modules
dist
build
coverage
.next
.astro
.vercel
*.min.js
package-lock.json
pnpm-lock.yaml
yarn.lock

ここでよくやる失敗が、src/generated/やOpenAPIから自動生成したAPIクライアントを無視し忘れることです。Claude Codeに小さな修正を頼んだだけなのに、生成コードが数千行整形されてレビュー不能になる。生成コードは整形するものではなく、生成元のスキーマを直して作り直すものなので、.prettierignoreに必ず入れておきます。

逆に.prettierignoreを広げすぎるのもダメです。src/**みたいに主要コードを丸ごと無視したら、Prettierを入れた意味がなくなる。無視するのは生成物・キャッシュ・巨大ファイル・外部ツール管理のファイルだけに絞ります。

エディタの保存時整形とCIで、人の目に頼らず止める

設定ファイルを置いても、走らせ忘れたら意味がありません。だから2か所で自動的に走らせます。

ひとつ目はエディタの保存時整形。VS Codeなら、ワークスペースに.vscode/settings.jsonを置きます。

{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true,
  "prettier.requireConfig": true,
  "[typescript]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
  "[typescriptreact]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
  "[json]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
  "[mdx]": { "editor.defaultFormatter": "esbenp.prettier-vscode" }
}

prettier.requireConfig を true にしているのが大事です。これでPrettier設定があるプロジェクトでだけPrettierが動くようになる。冒頭の僕の900行事故、原因はまさにこれを切っていて、設定のないリポジトリでエディタのデフォルト整形が暴走したことでした。trueにしてからは、二度と起きていません。

ふたつ目はCIです。GitHub Actionsなら、この最小構成で十分。

name: format

on:
  pull_request:
  push:
    branches: [main]

jobs:
  prettier:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run format:check

CIではformat:checkだけを使い、CI上で自動修正はしないのが分かりやすいです。落ちたら手元でnpm run formatして直す。Claude CodeにPR作成まで任せる運用だと、このCIが特に効きます。人間がレビューを始める前に、整形漏れを機械が止めてくれるからです。

コミットの瞬間に、触ったファイルだけ整形したくなったら、huskyとlint-stagedの出番です。毎回prettier . --writeを全体に走らせると重いので、staged filesだけに絞る。設定の詳しい手順はhusky + lint-stagedで「壊れたコードをコミットさせない」門番をつくるにまとめたので、コミット前の自動整形まで踏み込みたい人はそちらへ。

コピペで試す：競合チェックまで一気に通す

ここまでの設定を、空のディレクトリで端から端まで確認できる手順をまとめておきます。そのまま貼って動きます。

# 1. 準備
mkdir prettier-demo && cd prettier-demo
npm init -y

# 2. Prettierとeslint-config-prettierをバージョン固定で入れる
npm install --save-dev --save-exact prettier
npm install --save-dev eslint @eslint/js typescript-eslint eslint-config-prettier

# 3. わざと崩したファイルを置く
printf 'const   x=1\nconst y =    {a:1,b:2}\n' > sample.ts

# 4. .prettierrc を作る
cat > .prettierrc <<'JSON'
{ "printWidth": 100, "semi": true, "singleQuote": false, "trailingComma": "all", "endOfLine": "lf" }
JSON

# 5. 整形チェック（崩れているので落ちる）
npx prettier . --check

# 6. 整形を実行して直す
npx prettier . --write

# 7. もう一度チェック（今度は通る）
npx prettier . --check

5番でいったん失敗し、6番で直り、7番で通る。この「落ちる→直す→通る」を一度自分の目で見ておくと、formatとformat:checkの違いが腹落ちします。ESLint側を足したら、前述のnpx eslint-config-prettier eslint.config.jsで競合チェックまで回しておきましょう。

よくある質問

Q. PrettierとESLint、両方いりますか? 役割が違うので両方使うのが普通です。Prettierが見た目、ESLintが中身（未使用変数やバグの種）。併用するときだけeslint-config-prettierで見た目系ルールの競合を消します。

Q. .prettierrcに大量のオプションを書くべき? いいえ。Prettierは「決めることを減らす」思想のツールです。printWidthやendOfLineなど揺れやすい数項目だけ決めて、残りはデフォルトに任せるほうがメンテが楽です。

Q. eslint-config-prettierを入れたのに競合が残ります。 Flat Configでは配列の最後に置いていますか。先頭や途中だと、後ろのプリセットが見た目ルールを復活させます。npx eslint-config-prettier eslint.config.jsで残っているルールを特定できます。

Q. .prettierignoreと.gitignoreは何が違いますか? 目的が違います。.gitignoreはGitに入れないファイル、.prettierignoreは整形しないファイル。Prettierは.gitignoreも参照しますが、生成物や巨大ファイルは.prettierignoreにも明示しておくと意図が伝わりやすいです。

Q. WindowsとMacが混在するチームで差分が汚れます。 .prettierrcに"endOfLine": "lf"を入れてください。改行コードの違いでファイル全体が差分になる事故を防げます。Gitのcore.autocrlf設定とあわせて見直すとさらに安定します。

実際に試した結果

冒頭の900行PR以来、僕がPrettierでまず触るのは.prettierrcの中身より、prettier.requireConfig: trueとeslint-config-prettierの位置です。この二つを直しただけで、勝手な整形の暴走とESLintとの喧嘩が両方止まりました。

手元の小さなTypeScript/MDXリポジトリで端から流し直したところ、初回の全体整形のあとはformat:checkが安定して通り続け、Claude Codeに記事修正を頼んだ後のレビュー差分も、機能の変更だけが見える状態になりました。特に効いたのは、生成物を.prettierignoreから外したことと、CIをformat:checkだけに絞ったこと。設定そのものより、「どこで自動的に走らせるか」を決めたのが大きかった、というのが今の実感です。

こうしたPrettierやESLint、CLAUDE.md、検証チェックリストをセットにした運用テンプレートは教材一覧に整理しています。自分のリポジトリで動かしてみて、チーム標準に落とし込む土台として使ってください。