husky + lint-staged でコミット前に自動整形・Lintする

フォーマットの揺れや Lint 漏れは、レビューで指摘する前にコミット時に自動で直すのが一番です。husky（git フック管理）と lint-staged（ステージ済みファイルだけ処理）を組み合わせれば、数分で実現できます。

なぜ pre-commit で整形・Lintするのか

• フォーマット差分でレビューが埋もれるのを防ぐ
• 「Lint 通し忘れコミット」をなくす
• ステージしたファイルだけを対象にするので速い（全体を毎回走らせない）

CI でも Lint は回しますが、CI が落ちてから直すより、コミット前に手元で直る方が速いです。

セットアップ

pnpm add -D husky lint-staged
pnpm exec husky init

husky init で .husky/ が作られ、package.json に "prepare": "husky" が追加されます。 この prepare により、pnpm install のたびにフックが自動でセットアップされます（クローン直後も有効）。

pre-commit フックの設定

husky init が作る .husky/pre-commit は初期状態だとテスト実行になっているので、 lint-staged を呼ぶように書き換えます。

# .husky/pre-commit
pnpm lint-staged

lint-staged の設定

.lintstagedrc.json に「どのファイルに何をするか」を書きます。

{
  "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
  "*.{css,json,md,mjs}": ["prettier --write"]
}

• キー: ステージ済みファイルにマッチさせる glob
• 値: マッチしたファイルに実行するコマンド（配列は左から順に実行）
• マッチしたファイル名が引数として渡され、整形結果は自動で再ステージされる

動作の様子

git commit すると、pre-commit が lint-staged を呼び、ログが出ます。

[STARTED] *.{css,json,md,mjs} — 2 files
[STARTED] prettier --write
[COMPLETED] prettier --write
[SKIPPED] *.{ts,tsx} — no files
[STARTED] Staging changes from tasks...

.ts がステージされていなければスキップ、整形した分は再ステージ、と設定どおりに動きます。

ハマりどころ

• どうしてもフックを飛ばしたい時は git commit --no-verify
• tsc のようなファイル単位で動かないツールは lint-staged と相性が悪い。型チェックは CI 側に置くのが無難
• フックは「ステージ済みファイルだけ」が対象。意図せず対象外になっていないか、初回はログで確認する

CI との役割分担

• husky / lint-staged（手元）: コミット前に差分だけを素早く整形・Lint
• CI（GitHub Actions など）: プロジェクト全体に Lint・型チェック・ビルドをかける最終防衛ライン

二重に見えますが、役割が違います。手元で軽く弾き、CI で漏れを止める、の二段構えが効きます。

まとめ

husky + lint-staged は、コミット前の自動整形・Lint を数分で導入できます。設定は .husky/pre-commit と .lintstagedrc.json の2ファイルだけ。フォーマット論争から解放されて、 レビューを本質的な議論に集中させましょう。