ESLint・Prettierの設定と自動フォーマット（WordPressのテーマ・プラグイン開発向け）

WordPress のテーマやプラグインの JavaScript には、問題の検出を ESLint、見た目の整形を Prettier に任せ、保存時とコミット時に自動で実行する構成が扱いやすいです。この記事では、WordPress 公式の @wordpress/scripts を使う方法と、ESLint 9 の flat config で自前に組む方法の2通りを示し、エディターでの保存時整形、コミット前チェック、CI での確認までを設定します。

ESLint と Prettier の役割分担

ESLint は「未定義の変数を使っている」「使っていない変数がある」といった、バグにつながるコードを見つける道具です。Prettier はインデントや改行、引用符の種類などの書式だけを整える道具で、コードの意味には手を出しません。

両方を入れるときにつまずきやすいのが、ESLint の書式系ルールと Prettier の整形結果がぶつかる問題です。ESLint が「シングルクォートにせよ」と言い、Prettier がダブルクォートに直す、といった状態になると、保存のたびにコードが行ったり来たりします。これを避けるため、ESLint 側の書式系ルールを eslint-config-prettier で無効にし、書式は Prettier だけが決めるようにします。ESLint のルールとして Prettier を動かすプラグイン（eslint-plugin-prettier）もありますが、Prettier の公式ドキュメントは、動作が遅くなりエディターに書式の警告が大量に出ることなどから、多くの場合は別々に実行する構成を勧めています。

方法1: @wordpress/scripts を使う

ブロック開発などで @wordpress/scripts をすでに使っているなら、こちらが手早い方法です。WordPress の JavaScript コーディング規約に沿った ESLint 設定と Prettier 設定が同梱されており、設定ファイルを置かなくても既定の設定で動きます。

npm install --save-dev @wordpress/scripts

{
  "scripts": {
    "build": "wp-scripts build",
    "start": "wp-scripts start",
    "lint:js": "wp-scripts lint-js",
    "lint:css": "wp-scripts lint-style",
    "format": "wp-scripts format"
  }
}

npm run lint:js で ESLint、npm run format で Prettier による整形が走ります。ルールを調整したい場合は、プロジェクトに ESLint の設定ファイルを置き、@wordpress/eslint-plugin の推奨設定を継承して必要な部分だけ上書きします。Prettier の設定は .prettierrc に次の1行を書くと WordPress の設定を使えます。

"@wordpress/prettier-config"

注意点として、@wordpress/scripts が内部で使う ESLint のバージョンや、対応する設定ファイルの形式（従来の .eslintrc.* か、ESLint 9 の eslint.config.* か）は版によって異なります（2026年10月現在）。設定ファイルを置く前に、インストールした版の package.json の依存関係と公式ドキュメントで確認してください。また WordPress の規約は括弧の内側にスペースを入れる書き方を採用しており、標準の Prettier ではその書式になりません。@wordpress/scripts は WordPress 向けに調整した Prettier を使う構成になっているため、方法2と混ぜると整形結果が変わる点にも注意が必要です。

方法2: ESLint 9 の flat config で自前に組む

@wordpress/scripts を使わない小さなテーマや、ビルドを Vite などで行っているプロジェクトでは、必要なものだけを入れるほうが見通しがよくなります。

npm install --save-dev eslint @eslint/js globals eslint-config-prettier
npm install --save-dev --save-exact prettier

Prettier は版が変わると整形結果が少し変わることがあるため、公式ドキュメントでもバージョンを固定する --save-exact が勧められています。チーム内で版がずれると、触っていない行まで差分になるのを防ぐためです。

ESLint の設定は eslint.config.mjs に書きます。拡張子を .mjs にすると、package.json に "type": "module" がなくても import 構文で書けます。

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

export default [
  // ビルド成果物や外部ライブラリは対象外にする
  { ignores: ['build/**', 'dist/**', 'vendor/**', '**/*.min.js'] },

  js.configs.recommended,

  {
    files: ['**/*.js'],
    languageOptions: {
      ecmaVersion: 'latest',
      sourceType: 'module',
      globals: {
        ...globals.browser,
        jQuery: 'readonly',
        wp: 'readonly',
      },
    },
    rules: {
      'no-unused-vars': 'warn',
    },
  },

  // 書式系ルールを無効化する。最後に置いて他の設定を上書きさせる
  eslintConfigPrettier,
];

globals に jQuery と wp を入れているのは、WordPress が読み込むグローバル変数を「未定義」と誤検出させないためです。wp_localize_script() や wp_add_inline_script() で独自のグローバル変数を渡している場合も、ここに追加します。旧来のスクリプトで sourceType: 'module' が合わないファイルがあれば、そのファイルだけ別のブロックで 'script' を指定します。

Prettier の設定は .prettierrc.json と .prettierignore に書きます。

{
  "singleQuote": true,
  "useTabs": true,
  "printWidth": 100
}

build/
dist/
vendor/
*.min.js

設定ができたら、まず手動で動かします。

npx eslint .            # 問題の検出
npx eslint . --fix      # 自動で直せるものを修正
npx prettier . --check  # 整形が必要なファイルを一覧
npx prettier . --write  # 整形を実行

既存のプロジェクトに導入すると、最初の --write で多くのファイルが書き換わります。この整形だけを1つのコミットにまとめ、そのコミットの ID をリポジトリ直下の .git-blame-ignore-revs に書いておくと、git blame で整形コミットを飛ばして本来の変更者をたどれます（git config blame.ignoreRevsFile .git-blame-ignore-revs で有効化します）。

エディターで保存時に自動フォーマットする

VS Code では、拡張機能「ESLint」（dbaeumer.vscode-eslint）と「Prettier - Code formatter」（esbenp.prettier-vscode）を入れ、プロジェクトの .vscode/settings.json に次を書きます。

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  }
}

保存すると Prettier で整形され、ESLint で自動修正できる問題も直ります。この設定ファイルをリポジトリに含めれば、チーム全員の保存時の動きをそろえられます。codeActionsOnSave の値の書き方は VS Code の版で変わってきた経緯があるので、効かない場合は拡張機能のドキュメントを確認してください。保存しても整形されないときは、ステータスバーの Prettier の表示やコマンドパレットの「出力」で、設定ファイルが読み込まれているかを見るのが近道です。

コミット前と CI でチェックする

エディターの設定は人によって外れることがあるため、コミット時と CI でも確認します。コミット前のチェックには husky と lint-staged を使い、変更したファイルだけを対象にします。

npm install --save-dev husky lint-staged
npx husky init

npx husky init で作られる .husky/pre-commit の中身を npx lint-staged に書き換え、package.json に対象を指定します。

{
  "lint-staged": {
    "*.js": ["eslint --fix", "prettier --write"],
    "*.{css,scss,json,md}": "prettier --write"
  }
}

コミット前フックは git commit --no-verify で飛ばせるので、最後の砦は CI です。GitHub Actions なら、プルリクエストごとに次のように確認します。

name: Lint
on: [pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npx eslint .
      - run: npx prettier . --check

CI では --fix や --write を使わず、検出だけにします。CI が勝手に直すと、手元のコードと差が出て混乱するためです。アクションのメジャーバージョンや Node.js のバージョンは、利用時点の推奨に合わせて更新してください。

PHP はどうするか

Prettier は標準では PHP を整形しません。WordPress の PHP には、PHP_CodeSniffer と WordPress Coding Standards（WPCS）を使うのが一般的で、ESLint・Prettier とは別に CI に組み込みます。Prettier の PHP 用プラグインもありますが、WPCS の書式とは一致しない部分があるため、両方を同じファイルに使うと指摘と整形がぶつかります。PHP はどちらか一方に決めてください。

まとめ

• ESLint は問題の検出、Prettier は書式の整形と役割を分け、eslint-config-prettier で衝突を防ぎます。
• @wordpress/scripts を使う場合は wp-scripts lint-js と wp-scripts format で WordPress 規約に沿った設定がすぐ使えます。設定形式は版ごとに確認します。
• 自前で組む場合は ESLint 9 の eslint.config.mjs に ignores、推奨設定、WordPress のグローバル変数、最後に eslint-config-prettier を並べます。
• 保存時整形は VS Code の設定をリポジトリに含めてそろえ、husky と lint-staged でコミット前、CI で最終確認をします。
• 導入時の一括整形は1コミットにまとめ、.git-blame-ignore-revs に登録します。

• WordPressのブロック開発入門
• GitHub ActionsでCI/CDを構築する方法