インデントは人が指摘しない — ESLintとPrettier

ESLintとPrettier。コードの書類と確認用の虫眼鏡、行を整える定規とチェック。

ここまでで、「動くかどうか」を機械が確かめてくれる状態はできました。CI/CDの回でサーバー側に、前回でフロント側に、テストを置いて GitHub Actions で走らせています。

前回: 型は実行時には消える — TypeScriptを後から入れる 作業場所はVMの中(Ubuntu)です。~/server と ~/react-demo/ の両方をそのまま使います。

しかし、機械が何も言ってくれないものが、まだ2つ残っています。

  1. 「動くけれど、たぶん間違い」なコード。 変数名を打ち間違えているのに、その行にたどり着くまで誰も気づかない
  2. 書き方のばらつき。 インデントが2つだったり4つだったり、クォートが ' だったり " だったり、行末のセミコロンがあったり無かったり

2つ目は「どうでもいい」と思うかもしれません。 実際、どうでもいいです。 どちらでも動きます。

問題は、どうでもいいことに人間が時間を使ってしまうことです。この記事の目的は、コードをきれいにすることではありません。 どうでもいいことで悩む時間と、他人と揉める時間を、ゼロにすることです。

対象レベル: 初級 / 区分: 必修

目次

この記事でわかること

  • リンタとフォーマッタは別物だということ。ESLint は間違いを見つける道具、Prettier は見た目を揃える道具。役割が違うので、片方だけでは足りない
  • ESLint の設定ファイルには古い形と新しい形の2種類があり、ネット上の記事は圧倒的に古い形が多いこと。見分けられないと、コピペした設定が丸ごと無視される
  • ESLint と Prettier は放っておくと喧嘩すること。整形のルールを両方が持っているので、片方を黙らせる必要がある
  • 手元で直っているかどうかは、あてにならないこと。設定を入れ忘れた人が1人いれば終わるので、最後はCIで止める
  • 既存のコードに後から入れると、警告が数百個出ること。そこで全部直そうとすると必ず失敗する

この記事でやること

  1. ESLint を ~/server と ~/react-demo/ に入れ、新しい形(フラット設定)で eslint.config.mjs を書く
  2. Prettier を入れ、.prettierrc.json と .prettierignore を置く
  3. eslint-config-prettier で、ESLint 側の整形ルールを全部黙らせる
  4. VS Code の設定を書き、保存した瞬間に自動で直る状態にする
  5. CIに lint を足し、手元で直っていなくてもCIが止めるようにする
  6. 警告が大量に出る状態から、段階的に減らすやり方を決める

先に知る言葉

この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。

言葉意味
リンタ(linter)コードを読んで「これは間違いでは」と指摘する道具。動かさずに調べる
フォーマッタ(formatter)コードの見た目を、決めた形に揃え直す道具。意味は変えない
静的解析プログラムを実行せずに、書かれた文字だけを読んで調べること。リンタはこれ
ルールESLint の指摘1つ1つ。no-unused-vars のような名前が付いている
フラット設定ESLint 9 以降の新しい設定の書き方。eslint.config.js に配列を書く
.eslintrc古い設定の書き方。ネット上の記事の大半はこちら。ESLint 9 では既定で読まれない

① リンタとフォーマッタは、何が違うのか

名前が似ているせいで、どちらか片方でいいと思われがちです。違います。

ESLint(リンタ)Prettier(フォーマッタ)
何をするか間違いを見つける見た目を揃える
見ているものコードの意味コードの形
例「その変数、宣言していません」「その行、80文字を超えたので折ります」
直せないことがあるある(人が判断するしかない)無い(機械的に決まる)
設定でよく揉めるか揉める(何を間違いとするか)揉めない(どちらでもいい話なので)

具体的に見ます。

const tasks = [];
function addTask(title) {
  if (titel === '') return;
  tasks.push(title)
}

このコードには、性質の違う問題が2つあります。

  • 3行目の titel — title の打ち間違いです。これは間違いです。 実行すると ReferenceError で落ちます。見つけるのが ESLint の仕事
  • 4行目にセミコロンが無い — 間違いではありません。 JavaScript は自動で補うので、そのまま動きます。揃えるのが Prettier の仕事

ここが一番大事なところです。

ESLint は「間違いかどうか」を判断します。だから、人が設定を考える必要があります。 Prettier は「どちらでもいいこと」を機械的に決めます。だから、人が考える必要がありません。

「どちらでもいいこと」を ESLint で管理しようとすると、設定を考える人(=あなた)が延々と悩むことになります。 そこを Prettier に丸投げするのが、この記事の作戦です。


② なぜ、人がやらないのか

「レビューで指摘すればいいのでは」と思うかもしれません。 ここは、道具の話より先に片づけます。

インデントがずれたコードが上がってきたとします。 人間がやると、こうなります。

  1. レビューする人が気づく(時間を使う)
  2. コメントを書く(時間を使う)
  3. 書いた人が直す(時間を使う)
  4. もう一度レビューする(時間を使う)
  5. これが、変更のたびに、永遠に繰り返される

4人分の時間を使って、動作は1ミリも変わりません。

それだけではありません。 指摘された側は、内容ではなく人格を指摘された気になります。 「インデントが」「クォートが」と言われ続けると、レビュー自体が嫌になります。 逆に指摘する側も、毎回同じことを言うのが嫌になり、そのうち言わなくなります。 そして揃わなくなります。

機械にやらせる本当の理由は、楽をするためではありません。 「どちらでもいいこと」を、人間の口から出さないためです。機械が言えば、誰も傷つきません。

そしてもう1つ。 見た目が揃っていないコードは、Gitの差分が汚れます。

誰かが自分のエディタで保存し直しただけで、触っていない50行が「変更された」ことになります。 GitHubの回で見た差分表示が、実際に何を変えたのか読めなくなります。 これは実害です。

この記事の到達点は、ここです。

書き方について、人間が一度も口を開かない状態。


③ ESLint を入れる — 設定ファイルが2種類ある

先に、この記事で一番はまるところを書きます。

ESLint は 2024年のバージョン9で、設定ファイルの形式が完全に変わりました。 そして、ネット上の解説記事の大半は、それ以前のものです。

見分け方

検索して出てきた記事が、どちらの話をしているか。 これで判断できます。

古い(.eslintrc)新しい(フラット設定)
ファイル名.eslintrc.json / .eslintrc.js / .eslintrc.cjseslint.config.js / eslint.config.mjs
中身の形オブジェクト1つ配列(設定を上から順に重ねる)
他人の設定を使う"extends": ["eslint:recommended"]js.configs.recommended を import して配列に入れる
実行環境の指定"env": { "node": true }languageOptions.globals
プラグイン"plugins": ["react"](文字列)plugins: { react }(import した実体)
除外ファイル.eslintignore という別ファイル設定の中の ignores
対象の拡張子eslint . --ext .js,.jsx--ext は廃止。設定の files で指定

目印は3つです。

  1. .eslintrc という文字が出てきたら古い
  2. env: と書いてあったら古い
  3. --ext が出てきたら古い

古い形の設定ファイル(.eslintrc.*)だけを置くと、ESLint 9 は「eslint.config.* が見つからない」というエラーで止まります。 厄介なのは、新しい形と一緒に置いたときです。このとき古い形は黙って無視されます。 「設定したのに何も指摘されない」の原因は、たいていこれです。 ファイルを置いた気になっているだけで、ESLint は eslint.config.* の中身だけで動いています。

自分がどちらを使うかは、バージョンで決まります。

bash
$ cd ~/server
$ npx eslint --version

v9. で始まっていれば、新しい形です。 この記事は新しい形だけを扱います。

~/server に入れる

bash
$ cd ~/server
$ npm install --save-dev eslint @eslint/js globals

3つ入れました。 役割が違います。

パッケージ何か
eslint本体
@eslint/jsESLint 公式の「推奨ルール集」。本体とは別売りになった
globals「Node.js にはこういう変数が最初からある」という一覧。process や console の名前が入っている

globals が要る理由は、ESLint が「宣言されていない変数」を間違いとして指摘するからです。console.log の console はどこにも宣言されていないので、教えてやらないと console is not defined と怒られます。

eslint.config.mjs を作る

bash
$ nano ~/server/eslint.config.mjs
import js from '@eslint/js';
import globals from 'globals';

export default [
  { ignores: ['node_modules/', 'coverage/'] },

  js.configs.recommended,

  {
    files: ['**/*.js'],
    languageOptions: {
      ecmaVersion: 2024,
      sourceType: 'commonjs',  // ~/server は require で書いている
      globals: { ...globals.node },
    },
    rules: {
      'no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
    },
  },
];

上から順に読みます。

行意味
export default [ ... ]配列。上から順に重なり、後のものが前を上書きします
{ ignores: [...] }見ないファイル。 node_modules/ を見に行くと、他人のコードを全部検査して終わりません
js.configs.recommended公式の推奨ルール集。 ここが「よくある間違い」の本体
files: ['**/*.js']この設定を適用する対象。 ** は「どの階層でも」
sourceType: 'commonjs'require を使う書き方(CommonJS)だと宣言(import / export なら 'module')
globals.nodeNode.js に最初からある名前の一覧を読み込む
no-unused-vars使っていない変数の指摘。_ で始まる引数だけは見逃す設定にしています

なぜ eslint.config.js ではなく eslint.config.mjs なのか。 ~/server の package.json に "type": "module" が無い場合、.js のファイルは「古い書き方(CommonJS)」として読まれます。 そこに import を書くと構文エラーです。 .mjs は「これは import を使う新しい書き方だ」と拡張子で宣言する形です。どちらのプロジェクトでも動くので、迷ったら .mjs にしてください。

走らせる

bash
$ cd ~/server
$ npx eslint .

何も指摘が無ければ、何も出力されずに終わります。 無言が成功です。

わざと1つ間違えてみます。

bash
$ cd ~/server
$ echo "const unusedThing = 1;" >> lib/validate.js
$ npx eslint .
/home/ユーザー名/server/lib/validate.js
  42:7  warning  'unusedThing' is assigned a value but never used  no-unused-vars

✖ 1 problem (0 errors, 1 warning)

行番号 / 種類 / 説明 / ルール名の順です。一番右がルール名で、検索するときはこれを使います。

確かめたら戻します。

bash
$ cd ~/server
$ git checkout lib/validate.js

~/react-demo/ にも入れる

フロント側は、素の JavaScript ではないので少し足します。

bash
$ cd ~/react-demo
$ npm install --save-dev eslint @eslint/js globals eslint-plugin-react eslint-plugin-react-hooks
bash
$ nano ~/react-demo/eslint.config.mjs
import js from '@eslint/js';
import globals from 'globals';
import react from 'eslint-plugin-react';
import reactHooks from 'eslint-plugin-react-hooks';

export default [
  { ignores: ['dist/', 'node_modules/', 'coverage/'] },

  js.configs.recommended,

  {
    files: ['**/*.{js,jsx}'],
    languageOptions: {
      ecmaVersion: 2024,
      sourceType: 'module',
      globals: { ...globals.browser },
      parserOptions: {
        ecmaFeatures: { jsx: true },
      },
    },
    plugins: {
      react,
      'react-hooks': reactHooks,
    },
    rules: {
      'no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
      'react/jsx-uses-vars': 'error',
      'react-hooks/rules-of-hooks': 'error',
      'react-hooks/exhaustive-deps': 'warn',
    },
  },

  {
    files: ['**/*.test.jsx', 'src/setupTests.js'],
    languageOptions: {
      globals: {
        describe: 'readonly',
        it: 'readonly',
        test: 'readonly',
        expect: 'readonly',
        vi: 'readonly',
        beforeEach: 'readonly',
        afterEach: 'readonly',
      },
    },
  },
];

足したものは4つだけです。理由を1つずつ書きます。

足したものなぜ要るか
ecmaFeatures: { jsx: true }これが無いと <li> の < で構文エラーになります。ESLint は既定で JSX を読めません
react/jsx-uses-varsこれが無いと、import TaskList from ... が「使っていない」と警告されます。 ESLint 本体は JSX の中で使われていることを認識できません
react-hooks/rules-of-hooksif の中で useState を呼ぶような、Reactの回で触れたルール違反を止めます。これは本物のバグです
テストファイル用のブロックdescribe や expect は Vitest が実行時に用意する名前です。教えないと 'describe' is not defined が全部のテストで出ます

eslint-plugin-react は入れましたが、推奨ルール集は読み込んでいません。 推奨ルール集にはprop-types など、この書き方だと警告が大量に出るルールが入っています(整形系の jsx-indent などは入っていませんが、有効にすると Prettier と正面衝突します)。 いま要るのは jsx-uses-vars の1つだけです。⑨で、この考え方をもう一度書きます。

bash
$ cd ~/react-demo
$ npx eslint .

ここで警告が何十個も出ても、いま直さないでください。⑧で扱います。


④ Prettier を入れる

こちらは、考えることがほとんどありません。それが Prettier の売りです。

bash
$ cd ~/server
$ npm install --save-dev prettier
bash
$ nano ~/server/.prettierrc.json
{
  "semi": true,
  "singleQuote": true,
  "printWidth": 100,
  "trailingComma": "all",
  "endOfLine": "lf"
}
設定意味
semi行末のセミコロンを付ける
singleQuote文字列のクォートを ' にする
printWidthこの文字数を超えたら折り返す(80が既定。100は少し広め)
trailingComma配列やオブジェクトの最後の要素にもカンマを付ける
endOfLine改行コード。lf(既定)

endOfLine: "lf" は、道具を入れる回で VS Code の files.eol を \n にしたのと同じ話です。 あそこは「エディタが何を書き込むか」、ここは「Prettier が整形するときに何を書き込むか」。 別の設定なので、両方 LF に揃えておきます。 片方が CRLF だと、保存するたびに全行が変更扱いになります。

設定はこれだけにしてください。 Prettier の設定項目は他にもありますが、増やすほど「揉める材料」が増えます。 増やす価値があるのは、printWidth くらいです。

除外するものを書く

bash
$ nano ~/server/.prettierignore
node_modules
dist
coverage
package-lock.json

package-lock.json を必ず入れてください。 あれは機械が生成するファイルで、人が整形するものではありません。整形すると、次に npm install した瞬間に元に戻り、毎回巨大な差分が出ます。

走らせる

いきなり書き換えると怖いので、まず「何が変わるか」だけ見ます。

bash
$ cd ~/server
$ npx prettier --check .
Checking formatting...
[warn] lib/validate.js
[warn] test/validate.test.js
[warn] Code style issues found in 2 files. Run Prettier with --write to fix.

--check は、直しません。 「揃っていないファイルの一覧」を出して、1つでもあれば失敗(終了コード1)で終わります。 ⑦のCIで使うのはこちらです。

では直します。

bash
$ cd ~/server
$ git status
$ npx prettier --write .
$ git diff --stat

--write を実行する前に、必ず git status で「変更が無い状態」を確認してください。 --write はファイルを直接書き換えます。 コミットしていない編集が混ざっていると、あとで「自分の変更」と「Prettier の変更」を切り分けられなくなります。

git diff を見ると、クォートやインデントだけが変わっているはずです。 意味が変わっている行が1つでもあったら、そこは読んでください(普通はありません)。

~/react-demo/ にも、同じものを入れます。

bash
$ cd ~/react-demo
$ npm install --save-dev prettier
$ cp ~/server/.prettierrc.json ~/react-demo/.prettierrc.json
$ cp ~/server/.prettierignore ~/react-demo/.prettierignore

⑤ ESLint と Prettier を喧嘩させない

ここを飛ばすと、次のような状態になります。

  1. Prettier が「この行は100文字を超えたので、ここで折る」と整形する
  2. ESLint が「そのインデントは間違いです」と警告する
  3. ESLint の指摘どおりに直す
  4. 保存すると Prettier が元に戻す
  5. 1に戻る

両方が「整形」について意見を持っているからです。片方を黙らせます。

黙らせるのは ESLint 側です。 理由は簡単で、Prettier のほうが整形は得意だからです。

bash
$ cd ~/server
$ npm install --save-dev eslint-config-prettier

eslint.config.mjs に2行足します。

import js from '@eslint/js';
import globals from 'globals';
import prettier from 'eslint-config-prettier';

export default [
  { ignores: ['node_modules/', 'coverage/'] },

  js.configs.recommended,

  {
    files: ['**/*.js'],
    languageOptions: {
      ecmaVersion: 2024,
      sourceType: 'commonjs',  // ~/server は require で書いている
      globals: { ...globals.node },
    },
    rules: {
      'no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
    },
  },

  prettier,
];

eslint-config-prettier の中身は、「オフにする」だけの設定です。 何も指摘しません。Prettier と衝突する ESLint のルールを、片っ端から無効にします。

配列の一番最後に置いてください。 フラット設定は、後に書いたものが前を上書きします。 途中に置くと、その後ろで有効にされたルールが生き残って、また喧嘩します。

~/react-demo/ も同じです。 インストールして、import して、配列の最後に prettier を置きます。

bash
$ cd ~/react-demo
$ npm install --save-dev eslint-config-prettier

やらないほうがいいこと

「eslint-plugin-prettier を入れて、Prettier を ESLint のルールとして動かす」という書き方が、検索するとよく出てきます。

入れないでください。 理由は3つです。

  • 整形のずれが、全部「ESLintのエラー」として赤く出ます。 本物のバグと、クォートの向きが、同じ見た目で並びます
  • 遅くなります。 ファイルを開くたびに、ESLint の中で Prettier が丸ごと動きます
  • 役割が混ざります。 この記事の①でやった整理が、また崩れます

別々の道具として、別々に走らせるのが一番わかりやすいです。

npm scripts にまとめる

毎回 npx と打つのは続きません。 package.json の scripts に足します。

{
  "scripts": {
    "test": "node --test",
    "lint": "eslint .",
    "format": "prettier --write .",
    "format:check": "prettier --check ."
  }
}

~/react-demo/ の scripts にも、lint / format / format:check の3つを同じように足してください(test は前回入れた vitest run のままです)。

bash
$ cd ~/server
$ npm run lint
$ npm run format:check

⑥ 保存した瞬間に直す

コマンドで直せるようになりましたが、これでは続きません。 打つのを忘れるからです。

保存した瞬間に自動で直るようにします。 VS Code から VM を直接編集する回の続きです。

拡張機能は「VM側」に入れる

ここが Remote-SSH の一番の落とし穴です。

VS Code の拡張機能には、「手元のWindowsで動くもの」と「接続先のVMで動くもの」があります。 ESLint と Prettier の拡張機能は、後者です。 コードもパッケージもVMの中にあるので、当然です。

  1. VMに接続した状態で、Ctrl + Shift + X で拡張機能の一覧を開く
  2. ESLint(発行元 Microsoft、ID は dbaeumer.vscode-eslint)を探す
  3. ボタンが「インストール」ではなく「SSH: 〜 にインストール」になっていることを確認して押す
  4. 同じ手順で Prettier - Code formatter(発行元 Prettier、ID は esbenp.prettier-vscode)も入れる

[スクリーンショット: 01_拡張機能をVM側に入れる.png] 拡張機能の画面で、ボタンに SSH: ... にインストール と書かれているところを撮ってください。ホスト名が写るので、隠したければ塗りつぶして構いません。

手元側にだけ入っていると、拡張機能は「動いているのに何も指摘しない」状態になります。 VM側のファイルも node_modules も見えていないためです。エラーも出ないので、一番気づきにくい失敗です。

設定を書く

設定は、ユーザー設定ではなく、プロジェクトの中に置きます。

bash
$ mkdir -p ~/server/.vscode
$ nano ~/server/.vscode/settings.json
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "files.eol": "\n"
}
設定何をするか
editor.formatOnSave保存時に整形する(Prettier が走る)
editor.defaultFormatterどの拡張機能で整形するか。 指定しないと「複数あります」と聞かれ続けます
editor.codeActionsOnSave保存時に ESLint の自動修正も走らせる。"explicit" は「保存したときだけ」の意味
files.eol改行コード。 ④の .prettierrc.json と揃えます

なぜ .vscode/settings.json(プロジェクトの中)に置くのか。 ユーザー設定に書くと、自分のマシンでしか効きません。 プロジェクトに置いてGitにコミットすれば、そのコードを触る全員に同じ設定が配られます。 「設定した人だけ揃う」は、揃っていないのと同じです。

~/react-demo/.vscode/settings.json にも、同じものを置いてください。

確かめる

~/server の適当なファイルを VS Code で開いて、わざと崩します。

const  x    =     "abc"

Ctrl + S で保存してください。 一瞬で、こうなります。

const x = 'abc';

[スクリーンショット: 02_保存で整形される.png] 崩した状態のコードと、保存後のコードを並べて撮ってください。1枚に入らなければ、保存後だけで構いません。

ESLint のほうも見ます。 存在しない変数を書くと、保存しても消えません。

console.log(titel);

赤い波線が出ます。 マウスを乗せると 'titel' is not defined no-undef と出ます。

[スクリーンショット: 03_eslintの赤い波線.png] titel に赤い波線が出て、ルール名 no-undef が見えている状態を撮ってください。

ここで、①の違いがはっきりします。 Prettier は保存すれば全部直ります。 ESLint は直りません。 titel が title の打ち間違いなのか、本当に別の変数なのかは、機械には決められないからです。 「自動で直るもの」と「人が読むしかないもの」が、見た目で分かれます。

確かめたら、崩したコードは消しておいてください。


⑦ CIで落とす — 手元が正しい保証はない

⑥まででも、日常はかなり楽になります。それでも足りません。

理由はこれです。

  • 拡張機能を入れ忘れた人がいる
  • .vscode/settings.json を、自分の好みで書き換えた人がいる
  • VS Code ではなく nano で直した(あなたも、たまにやります)
  • --no-verify でチェックを飛ばした

「全員がちゃんとやる」を前提にした仕組みは、必ず破れます。 最後の砦は、手元の外に置きます。

ci.yml に足す

前回の ci.yml に、各ジョブへ2ステップずつ足すだけです。

bash
$ nano ~/server/.github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  server-test:
    runs-on: ubuntu-latest

    steps:
      - name: コードを取得する
        uses: actions/checkout@v4

      - name: Node.js を用意する
        uses: actions/setup-node@v4
        with:
          node-version: '22'

      - name: 依存を入れる
        run: npm ci

      - name: テストを走らせる
        run: npm test

      - name: 書き方を確かめる
        run: npm run lint

      - name: 整形を確かめる
        run: npm run format:check

  web-test:
    runs-on: ubuntu-latest

    defaults:
      run:
        working-directory: web

    steps:
      - name: コードを取得する
        uses: actions/checkout@v4

      - name: Node.js を用意する
        uses: actions/setup-node@v4
        with:
          node-version: '22'

      - name: 依存を入れる
        run: npm ci

      - name: テストを走らせる
        run: npm test

      - name: 書き方を確かめる
        run: npm run lint

      - name: 整形を確かめる
        run: npm run format:check

足したのは、各ジョブの最後の4行だけです。

なぜ、テストの「後」に置くのか。 ステップは上から順で、1つ失敗するとそこで止まります。 lint を先に置くと、クォートが1つ違うだけで、テストが1本も走らないまま真っ赤になります。 知りたいのは「動くかどうか」が先、「書き方」が後です。大事なものから走らせます。

なぜこれで「落ちる」のか。 eslint も prettier --check も、問題を見つけると終了コード1で終わります。 GitHub Actions は、ステップのコマンドが0以外で終わったら失敗とみなします。そういう約束になっているだけです。

わざと落とす

bash
$ cd ~/server
$ nano lib/validate.js

どこかの行のインデントを、スペース1個ずらしてください。

bash
$ cd ~/server
$ git add lib/validate.js
$ git commit -m "わざと整形を崩す"
$ git push

数十秒後、Actions タブで 整形を確かめる のステップが赤くなります。

Checking formatting...
[warn] lib/validate.js
[warn] Code style issues found in 1 file. Run Prettier with --write to fix.
Error: Process completed with exit code 1.

[スクリーンショット: 04_ci_整形で落ちる.png] Actions の実行画面で、整形を確かめる のステップに赤い×が付いているところを撮ってください。

戻します。

bash
$ cd ~/server
$ git revert --no-edit HEAD
$ git push

これで、「手元で直っていなくても、機械が止める」状態になりました。


⑧ 既存のコードに後から入れると、警告が数百個出る

この記事の手順を、今日書いたばかりの小さなコードでやったなら、警告は数個で済みます。

問題は、何ヶ月も書いたコードに後から入れたときです。

✖ 428 problems (61 errors, 367 warnings)

ここで、ほぼ全員が同じ失敗をします。

「よし、全部直そう」

やめてください。 何が起きるかというと、

  • 数百ファイルを書き換える、巨大なコミットができる
  • その中に、うっかり動作を変えてしまった1行が混ざる
  • レビューできる人が誰もいない(差分が大きすぎる)
  • git blame が全部あなたの名前になり、「この行を書いた人」が分からなくなる
  • 途中で力尽きて、ESLint ごと消される

分けます。整形と、間違いを、別々に。

手順1: 整形だけ、1回のコミットで全部やる

Prettier の変更は、意味を変えません。 だから一括で構いません。 ただし、それだけのコミットにします。

bash
$ cd ~/server
$ git status
$ npm run format
$ git add -A
$ git commit -m "Prettier で全体を整形(動作の変更なし)"

コミットメッセージに「動作の変更なし」と書いてください。 後で git log を読む人(=あなた)へのメモです。

git blame が汚れる問題には、対策があります。

bash
$ cd ~/server
$ git log -1 --format=%H > .git-blame-ignore-revs
$ git config blame.ignoreRevsFile .git-blame-ignore-revs
$ git add .git-blame-ignore-revs
$ git commit -m "整形コミットを blame から除外する"

.git-blame-ignore-revs は、「このコミットは git blame で無視してほしい」というコミットIDの一覧です。これで、整形前に誰がその行を書いたかが、そのまま残ります。

手順2: ESLint は「エラー」だけ先に消す

ESLint の指摘には2段階あります。

意味どうするか
errorたいてい本物のバグ。no-undef などすぐ直す。数は少ない
warning直したほうがいいが、動く。no-unused-vars など後で減らす

まず、エラーだけ見ます。

bash
$ cd ~/server
$ npx eslint . --quiet

--quiet は、警告を隠してエラーだけ出します。 61個だったものが、5個になったりします。 そこだけ直します。

自動で直せるものは、直させます。

bash
$ cd ~/server
$ npx eslint . --fix

--fix は、Prettier の --write と違って「意味を変えうる」修正を含みます。 必ずコミットしてから実行し、git diff を読んでください。 全部読めない量なら、--fix は使わずに手で直したほうが安全です。

手順3: 警告は「増やさない」ことだけ約束する

残った367個の警告を、今日ゼロにする必要はありません。 今日より増えなければ十分です。

CIの lint を、こう変えます。

{
  "scripts": {
    "lint": "eslint . --max-warnings=367"
  }
}

--max-warnings は、「警告がこの数を超えたらCIを失敗にする」オプションです。いまの数をそのまま書きます。

あとは、時間があるときに減らして、減った数に書き換えるだけです。

"lint": "eslint . --max-warnings=340"

この「数字を減らす方向にだけ動かす」やり方は、大きなコードに後から仕組みを入れるときの定番です。「今日から新しく増えるものは止める。過去は少しずつ返す」。 新しく始めたプロジェクトなら、最初から --max-warnings=0 にしてください。 ゼロから始められるのは、最初の1回だけの特権です。

手順4: どうしても直せない1行

機械が間違っていることも、たまにあります。 そのときは、その1行だけ黙らせます。

// eslint-disable-next-line no-console
console.log('起動しました');

ルール名(no-console の部分)を必ず書いてください。 // eslint-disable-next-line とだけ書くと、その行の全ルールが無効になります。 本物のバグまで一緒に見逃します。 ファイル全体を黙らせる /* eslint-disable */ は、原則として使わないでください。 使うなら、なぜ黙らせたのかをコメントで隣に書きます。


⑨ ルールを増やしすぎない

ESLint のルールは、本体だけで200個以上あります。 プラグインを入れれば、さらに増えます。

全部有効にしたくなりますが、やめてください。 こうなります。

  • 警告が多すぎて、誰も読まなくなる
  • 本物のバグの指摘が、好みの指摘に埋もれる
  • 「このルール、要る?」という議論が始まる。 ①で書いた、一番避けたかったことです

判断の基準を1つに絞ります。

そのルールが指摘するものは、「バグ」か、「好み」か。 バグなら入れる。好みなら入れない。

ルールどちら判断
no-undef(未定義の変数)バグ入れる
no-unused-vars(未使用の変数)バグの予兆(消し忘れ・書き間違い)入れる(warn で)
react-hooks/rules-of-hooksバグ入れる
quotes(クォートの向き)好み入れない(Prettier の担当)
indent(インデント幅)好み入れない(Prettier の担当)
sort-imports(import の並び順)好み入れない
max-lines(1ファイルの行数上限)好み入れない(長い=悪い、とは限らない)

③で js.configs.recommended を使ったのは、これが理由です。 公式が「これはバグです」と判断したものだけが入っています。 自分で200個から選ぶより、まずこれで始めてください。

足すのは、実際に事故ってからです。

「この間バグを出したので、それを防ぐルールを1つ足す」なら、全員が納得します。 「一般によいとされているので足す」は、ほぼ必ず揉めます。

そして、揉めたときの結論はいつも同じです。

どちらでもいいことは、機械に決めさせる。決まった内容には、誰も文句を言わない。 Prettier が設定項目をあえて少なく絞っている(Option Philosophy)のも、同じ思想です。選べないから、揉めません。


⑩ つまずいたところ

設定を書いたのに、何も指摘されない

設定ファイルの名前が違うか、置き場所が違います。 .eslintrc.json を作っていませんか。 ESLint 9 は、eslint.config.* があると .eslintrc.* を黙って無視します(③)。プロジェクトの一番上に eslint.config.mjs があるか、ls -a で確認してください。

SyntaxError: Cannot use import statement outside a module

eslint.config.js に import を書いて、package.json に "type": "module" が無い状態です。ファイル名を eslint.config.mjs に変えれば直ります(③)。

テストファイルだけ 'describe' is not defined が大量に出る

Vitest が実行時に用意する名前を、ESLint が知らないからです。③のフロント側の設定の、最後のブロックを入れてください。

保存しても整形されない

順に確かめます。

  1. 拡張機能はVM側に入っているか(⑥)。手元にだけ入っているのが最頻出です
  2. 画面右下に Prettier と出ているか。 出ていなければ、そのファイルは Prettier の担当外です
  3. .prettierignore で除外していないか
  4. VS Code の出力パネル(Ctrl + Shift + U)で Prettier を選ぶと、なぜ動かなかったかが書いてあります

保存するたびに、勝手に元へ戻る

ESLint と Prettier が喧嘩しています(⑤)。eslint-config-prettier を入れ、配列の一番最後に置いているかを確認してください。途中に置くと効きません。

手元では通るのに、CIだけ落ちる

改行コードです。 .prettierrc.json の endOfLine と VS Code の files.eol の両方が LF になっているか確認してください(④)。CIは Linux なので、CRLF が混ざると全行が違うと判定されます。

npm ci のところでCIが落ちる

package-lock.json をコミットしていません。 今回パッケージを4〜6個足したので、package-lock.json は必ず変わっています。 git add package-lock.json を忘れないでください(CI/CDの回)。

npx eslint . が終わらない

ignores に node_modules/ を書き忘れています。 他人のコードを数万ファイル検査しています。Ctrl + C で止めてください。


後片づけ

今回入れたものは、この先ずっと使うので、消さないでください。

何を入れたかを確認するには、こうします。

bash
$ cd ~/server
$ cat package.json

元に戻したい場合は、package.json の devDependencies から今回入れたものを消して、設定ファイルを消します。

bash
$ cd ~/server
$ rm eslint.config.mjs .prettierrc.json .prettierignore
$ rm -rf .vscode
$ npm install

~/react-demo も同じです。 Prettier が整形したコード自体は残りますが、それで困ることはありません(動作は変わっていません)。

CIだけ止めたいときは、ci.yml から足した4行を消して push すれば戻ります。


まとめ

  • リンタとフォーマッタは別物。 ESLint は間違いを見つける、Prettier は見た目を揃える。片方だけでは足りない
  • ESLint は人が設定を考える必要がある。 「何を間違いとするか」は決まっていないから
  • Prettier は考える必要がない。 「どちらでもいいこと」を機械的に決めるだけだから
  • 人がレビューで指摘してはいけない。 4人分の時間を使って、動作は1ミリも変わらない。しかも言われた側は嫌になり、言う側もそのうち言わなくなる
  • 見た目が揃っていないと、Gitの差分が汚れる。 保存し直しただけで50行が「変更」になる。これは実害
  • ESLint の設定には古い形(.eslintrc)と新しい形(eslint.config.js)があり、記事の大半は古い。目印は .eslintrc / env: / --ext の3つ
  • 古い形だけなら ESLint 9 はエラーで止まる。新しい形と一緒に置くと、古い形は黙って無視される。 「設定したのに何も出ない」の原因はたいていこれ
  • フラット設定は配列。後に書いたものが前を上書きする
  • package.json に "type": "module" が無いなら、eslint.config.mjs(拡張子で宣言する)
  • React では react/jsx-uses-vars が要る。 無いと、JSXでしか使っていない import が「未使用」と警告される
  • テストの describe や expect は、globals として教えないと全部 no-undef になる
  • eslint-config-prettier を、配列の一番最後に置く。 途中だと効かず、保存のたびに元へ戻る無限ループになる
  • eslint-plugin-prettier は入れない。 整形のずれが、本物のバグと同じ赤さで並ぶ
  • .prettierignore に package-lock.json を必ず入れる。 機械が作るファイルを整形しない
  • VS Code の設定は .vscode/settings.json に置いてコミットする。 「設定した人だけ揃う」は揃っていないのと同じ
  • Remote-SSH では、拡張機能を「VM側」に入れる。 ボタンが SSH: 〜 にインストール になっているか見る。手元だけだと、無言で何もしない
  • 最後はCIで止める。 拡張機能を入れ忘れた人、nano で直した日、--no-verify した回。手元を信用する仕組みは必ず破れる
  • CIでは lint をテストの「後」に置く。 先だと、クォート1つでテストが1本も走らない
  • 既存コードに後から入れると数百個出る。一度に直さない
  • 整形は1コミットで一括、ただし「それだけ」のコミットにする。 .git-blame-ignore-revs で blame を守る
  • ESLint は --quiet でエラーだけ先に潰し、警告は --max-warnings の数字を減らす方向にだけ動かす
  • --fix は意味を変えうる。 必ずコミットしてから走らせ、差分を読む
  • // eslint-disable-next-line には、必ずルール名を書く。 書かないと本物のバグも見逃す
  • ルールを増やさない。 判断は1つ、「バグか、好みか」。好みは Prettier に渡す
  • 足すのは、実際に事故ってから。 「一般によいとされているので」は必ず揉める

これで、書き方について人間が口を開く必要が無くなりました。 ここまでの道具立て(テスト・CI・リンタ・フォーマッタ)は、どれも「人が気をつける」を「機械が止める」に置き換えたものです。気をつけるのは、続かないからです。

参考リンク


次に読む

この記事は 【第4段階】フロントエンド の 7 / 15 本目です。

記事
← 前の記事型は実行時には消える — TypeScriptを後から入れる
→ 次の記事divのボタンはキーボードで押せない — アクセシビリティ

上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。

全体の順路は はじめに にあります。

roadmap.sh のどこをやっているか

Frontend›Linters and Formatters
  • ESLint
  • Prettier
  • CIでの自動チェック

この記事は、上の項目を実際に手を動かして確かめる回です。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

コメント

コメントする

目次