AWS CDK × TypeScript 実践ガイド（ESLint / Prettier / VSCode）

「CDK を TypeScript で書くなら、どこまで整備するべきか？」を実務視点で整理したメモです。特に次の課題を潰すことを目的にしています。

VSCode の自動整形が効かない
除外ファイルが反映されない
ESLint / Prettier / TypeScript の責務が曖昧

この記事の結論

CDK の TypeScript 開発は、次の4点を分離して管理すると安定します。

Lint（ESLint）
Format（Prettier）
VSCode 保存時挙動
除外設定（lint/format対象外）

この順で問題を切り分けると、設定トラブルを素早く解消できます。

まず押さえる前提

Linter: ESLint
Formatter: Prettier
TypeScript 向け ESLint: typescript-eslint

typescript-eslint は、@typescript-eslint/parser と @typescript-eslint/eslint-plugin をまとめて扱えるため、依存関係の整合を取りやすいのが利点です。

参考:

インストール方針（ローカル開発依存）

BASH

npm install --save-dev eslint prettier typescript-eslint eslint-config-prettier

ポイント:

-g は使わず、プロジェクトローカルに固定
CI とローカルで同じバージョンを使う

設定例（Flat Config 前提）

eslint.config.mjs（例）

import js from "@eslint/js";
import tseslint from "typescript-eslint";
import eslintConfigPrettier from "eslint-config-prettier";

export default [
  {
    ignores: ["cdk.out/**", "dist/**", "node_modules/**"],
  },
  js.configs.recommended,
  ...tseslint.configs.recommendedTypeChecked,
  {
    files: ["**/*.ts"],
    languageOptions: {
      parserOptions: {
        projectService: true,
      },
    },
    rules: {
      "@typescript-eslint/no-explicit-any": "warn",
    },
  },
  eslintConfigPrettier,
];

prettier.config.cjs（例）

module.exports = {
  semi: true,
  singleQuote: false,
  trailingComma: "all",
  printWidth: 100,
};

.prettierignore（例）

TEXT

cdk.out
dist
node_modules

VSCode 自動整形が効かないときの確認順

.vscode/settings.json（例）

JSON

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

チェックポイント:

Default Formatter が Prettier か
ESLint 拡張と Prettier 拡張が有効か
ワークスペース設定とユーザー設定が衝突していないか
保存時に code action を always / explicit のどちらで運用するか統一できているか

「除外ファイルが効かない」時のよくある原因

ESLint 側

Flat Config では .eslintignore だけでは足りず、ignores を eslint.config.* に明示する必要がある

Prettier 側

.prettierignore に対象パスを記載していない
拡張子別のフォーマッタ設定が上書きされている

CDK 側で意識したいこと

同一プロジェクト内の CDK パッケージバージョンは揃える
cdk.out を lint/format 対象から外す
インフラコードもアプリコード同様に CI で静的検証する

参考:

参考資料

まとめ

CDK + TypeScript で安定運用するには、「Lint」「Format」「Editor挙動」「除外設定」を別問題として切り分けるのが最短です。設定を一度テンプレート化してしまうと、プロジェクト追加時の負担が大きく下がります。