📝

CDK に ESLint を導入する

に公開
AWS
TypeScript
ESLint
AWS CDK
tech

はじめに

この記事では、CDK プロジェクトに ESLint を導入する方法を紹介します。

ESLint とは？

そもそも、ESLint とは何でしょうか？

ESLint は、JavaScript や TypeScript などのコードを解析し、単純な構文エラーやコーディング規則に違反するコードを検出するツールです。

このツールを使用することで、チームのメンバー間でコーディング規則(書き方)を統一することができます。

https://eslint.org/

1. ESLint のインストール

それでは、CDK プロジェクトに ESLint を導入する手順を紹介します。

まず、以下のコマンドを実行して、必要なパッケージをインストールします
(今回は ESLint と、ESLint の TypeScript プラグインをインストールします)

# npm
npm install -D eslint typescript-eslint

# yarn
yarn add -D eslint typescript-eslint

# pnpm
pnpm install -D eslint typescript-eslint

2. package.json の設定

続いて、ターミナル上で ESLint のコマンドが実行できるように package.json の scripts に lint コマンドを追加します
(--fixオプションをつけると、自動的な修正が適用されます。)

package.json
{
  "scripts": {
+   "lint": "eslint .",
+   "lint:fix": "eslint . --fix"
  }
}

3. ESLint の設定ファイル作成

続いて、プロジェクトのルートにeslint.config.mjsを作成します

eslint.config.mjs
import eslint from "@eslint/js";
import tsEslint from "typescript-eslint";

export default tsEslint.config(
  // ESLintの推奨設定を適用
  eslint.configs.recommended,
  ...tsEslint.configs.recommended,
  {
    // lib と bin ディレクトリ配下の typescript ファイルを対象にする
    files: ["lib/**/*.ts", "bin/*.ts"],
    languageOptions: {
      parserOptions: {
        projectService: true,
        project: "./tsconfig.json",
      },
    },
    plugins: {},
    rules: {},
  },
  // 無視するファイル・ディレクトリを指定
  {
    ignores: ["cdk.out", "node_modules", "*.js"],
  }
);

4. エディタの拡張機能をインストール

最後に、ESLint に設定したルールに違反するコードをエディタ上で可視化できるように、拡張機能をインストールします。(VSCode の場合)
ここまでで、基本的な導入は完了です(簡単！！)

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

また、.vscode/settings.json に以下の内容を追記します

.vscode/settings.json
{
+ "eslint.useFlatConfig": true,
 ...
}

動作確認

基本的な導入が完了したので、以下の手順で動作確認を行います。

  1. あらかじめ以下のようなルール違反のコードを、lib ディレクトリ配下のファイルに含めておきます
lib/my-stack.ts
const a:any = ""
  1. 以下のコマンドを実行して、該当箇所がエラーになるかを検証します
# npm
npm run lint

# yarn
yarn lint

# pnpm
pnpm lint
トラブルシューティング

ターミナル上ではエラーが出るが、エディタ上では出ない

このような問題に直面した場合には、拡張機能のバージョンを見直す・エディタをリロード(または再起動)するなどの対応が有効だと考えられます。(エディタの問題であるため)


ターミナル上でエラーが出ない

このような問題に直面した場合には、npm run lint --debugを実行して、ESLint が正常に機能しているか確認することが有効だと考えられます。

詳しくは以下のドキュメントを参照ください

https://eslint.org/docs/latest/use/configure/debug

ルールのカスタマイズ

上記の eslint.config.mjs では recommended のルールを採用しました。
もし、その中でエラーになって欲しくないルール、その中にはないがエラーになって欲しいルール がある場合は、ESLint ルールをカスタマイズすることで解決できます。

ルールを変更する

例えば、「使用されていない変数があってもエラーにしたくない」という場合は、以下のように設定ファイルを修正します。

eslint.config.mjs
import eslint from "@eslint/js";
import tsEslint from "typescript-eslint";

export default tsEslint.config(
    // 省略
    rules: {
+     "no-unused-vars": "off",
+     "@typescript-eslint/no-unused-vars": "off"
    },
  },
);

プラグインを導入する

ESLint には eslint-plugin-awscdk という CDK 用の便利なプラグインがあり、このプラグインを使用することで以下ルールを適用することができます

https://eslint-plugin-awscdk.dev/ja/

命名規則に関するルール

概要 推奨ルールに含まれる
Construct の constructor プロパティには 'scope, id' または 'scope, id, props' を指定する ✅
Construct ID に "Construct" や "Stack" などの suffix をつけない ✅
Construct ID に 親 Construct の名前をつけない ✅
Construct ID に変数を使用しない ✅
Construct ID は PascalCase で書く ✅
Construct の Props は ${Construct名}Props の形式で書く

安全性に関するルール

概要 推奨ルールに含まれる
Props(Interface) のプロパティには "readonly" をつける ✅
Construct の public 変数には "readonly" をつける ✅
Props のプロパティに Construct 型を指定しない ✅
Construct の public プロパティに Construct 型を指定しない ✅
Construct の constructor の第二引数 (scope プロパティ) には必ず this を渡す ✅

モジュール構成に関するルール

概要 推奨ルールに含まれる
private ディレクトリ内のモジュールを、外部から呼び出さない

コメントに関するルール

概要 推奨ルールに含まれる
Props(Interface) のプロパティと Construct の public プロパティには JSDoc を書く
Props(Interface) のオプショナルなプロパティには '@default' JSDoc を書く

プラグインの導入手順

eslint-plugin-awscdkの導入手順は以下の通りです

1. プラグインのインストール

# npm
npm install --save-dev eslint-plugin-awscdk

# yarn
yarn add -D eslint-cdk-plugin

# pnpm
pnpm install -D eslint-plugin-awscdk

2. eslint.config.mjs の更新

eslint.config.mjs
import eslint from "@eslint/js";
import tsEslint from "typescript-eslint";
+import cdkPlugin from "eslint-plugin-awscdk";

export default tsEslint.config(
  // ESLintの推奨設定を適用
  eslint.configs.recommended,
  ...tsEslint.configs.recommended,
  {
    // libとbinディレクトリ配下のtsファイルを対象にする
    files: ["lib/**/*.ts", "bin/*.ts"],
+   extends: [cdkPlugin.configs.recommended],
    // ...その他の設定
  },
);

まとめ

今回は、CDK プロジェクトに ESLint を導入する方法を紹介しました。

ESLint の導入により、コードの品質向上とチーム開発の効率化が期待できます。
特に、eslint-plugin-awscdk を使用することで、CDK 特有のベストプラクティスも自動的にチェックできるようになります。

ESLint を使いこなして、快適な CDK 開発を行いましょう！！

ドキュメント

ESLint ドキュメント

https://eslint.org/docs/latest/

typescript-eslint ドキュメント

https://typescript-eslint.io/getting-started/

eslint-cdk-plugin ドキュメント(日本語)

https://eslint-plugin-awscdk.dev/ja/

Discussion