UZUMAKI TechBlog

ESLint, Prettierをチーム開発で運用する〜VSCode, Github Actions編〜

概要

チームでシステム開発する際に、コードの品質維持するためGithub上でPull Requestを使ってコードレビューをするのはもはや常識です。しかしすべてのコードを人力でレビューするのは効率的ではありません。静的解析やコードフォーマッターで自動化できるところは自動化し、人間はそれ以外の本質的なコードをレビューできるように設定します。
本稿ではNext.jsを使ったフロントエンドのプロジェクトを使い、開発者のマシンで静的解析ツールESLintおよびコードフォーマッターPrettierを使うよう促すためのVS Codeでの設定と、Github ActionsでPull Request作成時にESLint, Prettierを実行してコード品質のを保つ方法を提案します。

目的

SPAでフロントエンドを複数人で開発する際に静的解析ツールやフォーマッターで解決できるものは解決し、本質的な箇所をレビューしてレビューコストを下げることを目的とします。

対象読者

フロントエンジニア、リードエンジニア

本文

本件で扱うコードはこちらのリンクのNext.jsのサンプルプロジェクトに含まれています。

GitHub - konyu/base_next at cihttps://github.com/konyu/base_next/tree/ci

ESLint, Prettierを開発環境で設定する方法については前回のブログポストを参考にしてください

ESLint, Prettierをチーム開発で運用する〜VSCode, Github Actions編〜https://blog.uzumaki-inc.jp/eslint-prettiervscode-github-actions

VS CodeでESLintとPrettierを設定する

多くの開発者が使うエディタであるVS Code自体にESLintとPrettierでの利用を促進するために、リードエンジニア等開発基盤を整える人がリポジトリに追加することで実現できます。

下記の方式ではVS Codeにプラグインを強制してインストールはできないですが、プラグインのインストールやそのプロジェクト上での設定方法を共通化することができます。

この章では開発者のマシンで静的解析ツールESLintおよびコードフォーマッターPrettierを使うよう促すためのVS Codeでの設定します。

ESLintとPrettierのプラグインのリンク紹介

今回使うVS Codeのプラグインはこちら

ESLint

marketplace.visualstudio.comhttps://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint

Prettier

marketplace.visualstudio.comhttps://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode

.vscodeディレクトリに設定する設定ファイル

.vscodeディレクトリで、VSCodeでプロジェクトごとに共通させる設定をコード管理することがでます。

extensions.json に下記のようにインストールを推奨するプラグインを設定します。※あくまで推奨なので強制インストールはできません。

{
  "recommendations": [
    "dbaeumer.vscode-eslint", // eslint
    "esbenp.prettier-vscode" // prettier
  ]
}

settings.jsonにはプロジェクトごとの独自でVS Codeの設定をすることができます。(ファイルの形式ごとに細かく設定はできますが、シンプルなNext.jsのプロジェクトの場合支障は出ません)

{
  "editor.defaultFormatter": "esbenp.prettier-vscode", // フォーマッターをPrettierにする
  "editor.formatOnSave": true, // ファイル保存時にフォーマットを実行
  "eslint.codeActionsOnSave.mode": "all" // ファイル保存時にESLintを実行
}

推奨するプラグインが設定されるとVS Code起動時のダイアログが表示されます

上記ダイアログを無視しても、拡張機能から**@recommended** と入力すると対象のプラグインを表示することができます。

※ Git pre-commitでESLintやPrettierを使うのはどうか？

lint-stagedを使いgitのstageに上がっているファイルに対してESLintやPrettierをpre-commitでコミットする直前に実行させる事もできます。
個人的にはエディタでソースコードを保存時にESLintやPrettierを実行させるほうが、すぐに問題に気づくので便利だと思っています。
pre-commitもgit commit時にスキップすることができるので、VSCode上で実行するのと同様に開発者個人個人の端末でESLintやPrettierをすることはPull Requestの品質の保証にはなりません。

次の章では、品質を保証するためにGithubへプッシュしPull Requestを作成したリポジトリに対してESLintやPrettierを実行する方法を紹介します。

Github ActionsでESLint, Prettierを実行する

開発者のマシンで正しくESLintおよびPrettierが使われたかどうかは、どうしても漏れる可能性があります。チェックする最後の要として、Github ActionsでPull Request作成時にESLint, Prettier実行するように設定します。

この章では下記の設定について紹介します。

  • ESLintをPRの差分のファイルに対して実行し、指摘点をPRのコメントで追記する
  • PrettierをPRの差分のファイルに対して実行し、フォーマットした内容をコミットする

Github Actions上でファイル書き込みなどの権限を設定する

前準備としてGithub Actionsで実行時にコメントを書き込んだり、GITHUB_TOKENで書き込みできるように書き込みできるように変更する必要があります。

GITHUB_TOKENについての詳細は下記のリンクを参照してください。

Automatic token authentication - GitHub Docshttps://docs.github.com/ja/actions/security-guides/automatic-token-authentication

簡単に設定方法を書くと、GithubのリポジトリのSettingsのタブを開き、Actions → General → Workflow permissionsの中にある Read and write permissionsを選択してSaveボタンを押してください。

ESLintをGithub Actionsで実行する設定ファイル

reviewdogのESLintを実行するActionを使用します。reviewdogの便利な点は指摘点をPull Requestのコメントとして追記してくれるのでどういう問題が発生したのか簡単に見ることができます。

GitHub - reviewdog/action-eslint: Run eslint with reviewdoghttps://github.com/reviewdog/action-eslint

.github/workflows/eslint.yml

name: Linter
on: [pull_request]
jobs:
  eslint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: eslint
        uses: reviewdog/action-eslint@v1
        with:
          github_token: ${{ secrets.github_token }}
          reporter: github-pr-review
          eslint_flags: "src/**/*.{ts,tsx}"
          fail_on_error: true # 指摘が発生したらjobを失敗扱いにする

試しにESLintで指摘されるコードをコミットしてプッシュするとこのように表示されます。

PrettierをGithub Actionsで実行する設定ファイル

PrettierにはESLintのように都合のように差分のファイルのみフォーマットしてコミットするというのを一発でやってくれるGithub Actionが見つからなかったので、自前で作成しました。(prettier_actionも候補に上がったのですが、中のコードを読むとフォーマット対象のファイルに対するアプローチが違ったため不採用)

下記で紹介するYMLファイルで実行する内容は

  • ソースコード取得する
  • nodeをインストール & キャッシュを取得
  • prettier自体を実行
  • prettierでフォーマットしたファイルをコミット

.github/workflows/prettier.yml

name: Formatter
on: [pull_request]
jobs:
  prettier:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          ref: ${{ github.head_ref }}
      - uses: technote-space/get-diff-action@v6 #差分を取得する
        with:
          PATTERNS: |
            **/*.{ts,tsx,js,jsx,json}
      - uses: actions/setup-node@v3 #nodeをインストール & キャッシュを取得
        with:
          node-version: 18
          cache: "npm"
      - name: Run Prettier # prettier自体を実行
        run: |
          npm ci
          npx prettier --write ${{ env.GIT_DIFF_FILTERED }} # 環境変数GIT_DIFF_FILTEREDに差分のあるファイルが列挙されている
        if: env.GIT_DIFF
      - uses: stefanzweifel/git-auto-commit-action@v4 # フォーマットしたファイルをコミット
        with:
          commit_message: Apply Prettier Change

試しに、Prettierでフォーマットされるコードをコミットして、Github Actionsを動かしてみると下記のように自動でフォーマットされたコミットが追加するのを確認できます。

Github Actionsで失敗した場合にPRをマージできないようにする

Github Actionsを設定しただけでは、Github Actionsで失敗してもPRをマージできてしまいます。

そこでmainブランチへPull RequestはGithub Actionsが通らないとマージできないようリポジトリのブランチの設定を追加します。

Settings → Branches → Protect matching branches → Require status checks to pass before merging にてESLintの指摘がすべてクリアしないとマージできないようにします(Prettierは自動でフォーマットしコミットまでしてしまうので必要はありません)

まとめ

ESLintで静的解析し、PrettierでコードフォーマッターをVSCodeとGithub Actionsで利用できるようにしました。VSCodeでは設定をチーム全体に適用させるように促すよう設定ファイルをリポジトリに追加する方法を、Github Actionsでは最後の要としてESLintが通らないとマージできない設定することでコード健全化を図りました。

← 記事一覧へ