ESLint Plugin for AWS CDK

4.3.2 verified Sat Apr 25 auth: no javascript

An ESLint plugin providing custom lint rules for AWS CDK projects, including rules like 'require-jsdoc', 'no-unused-props', 'prevent-construct-id-collision', and 'no-construct-in-interface'. Current stable version is 4.3.2, released under an active development cadence. It requires TypeScript and leverages type information via typescript-eslint. Differentiates from generic CDK linting by being specifically tailored to CDK constructs and patterns, offering both recommended and strict configs. Supports ESLint 8/9/10 and TypeScript 4.8+ to 6.x, and ships its own TypeScript type definitions.

Common errors

error Error: Failed to load plugin 'awscdk' declared in '.eslintrc': Cannot find module 'eslint-plugin-awscdk' ↓

cause Plugin not installed or not in node_modules.

fix

Run npm install -D eslint-plugin-awscdk or pnpm install -D eslint-plugin-awscdk.

error TypeError: Cannot read properties of undefined (reading 'recommended') ↓

cause Trying to access configs.recommended from a default import that is not the plugin object (e.g., wrong import style).

fix

Use import cdkPlugin from 'eslint-plugin-awscdk' and then cdkPlugin.configs.recommended. Do not use destructured import.

error Error: 'eslint-plugin-awscdk' resolved in ESLint configuration to an unexpected value. ↓

cause ESLint version mismatch or plugin not found due to flat config vs classic config confusion.

fix

Use the correct config format: for flat config, import the plugin; for classic config, use the string 'eslint-plugin-awscdk' in plugins array.

error Parsing error: ESLint was configured to run on `<tsconfigRootDir>/file.ts` using `parserOptions.project` but it was not found. ↓

cause parserOptions.project is not set or tsconfig.json path is incorrect.

fix

Set parserOptions.project to './tsconfig.json' (or the correct path) in your ESLint config.

Warnings

breaking Since v4, the plugin requires ESLint 8.57.0 or later, dropping support for earlier ESLint 8 versions. ↓

fix Upgrade ESLint to ^8.57.0 || ^9.0.0 || ^10.0.0.

breaking Config names changed in v4: classic configs are now under 'plugin:awscdk/classicRecommended' and 'plugin:awscdk/classicStrict', not 'plugin:awscdk/recommended'. ↓

fix For classic .eslintrc, use 'plugin:awscdk/classicRecommended' instead of 'plugin:awscdk/recommended'. For flat config, use cdkPlugin.configs.recommended.

deprecated The package 'eslint-cdk-plugin' (v3.x) has been renamed to 'eslint-plugin-awscdk' (v4.x). v3.x is no longer maintained. ↓

fix Uninstall eslint-cdk-plugin and install eslint-plugin-awscdk@4. Update imports and config accordingly.

gotcha The plugin uses TypeScript type information. Ensure you have parserOptions.project set in classic config or use typed linting with typescript-eslint. ↓

fix Configure parserOptions.project in .eslintrc or use typescript-eslint's typed configs in flat config.

gotcha Some rules require type information and will not work without it, causing false positives or errors. ↓

fix Ensure you are using @typescript-eslint/parser with project option, or use only rules that do not require types.

deprecated Rule 'no-construct-in-public-property-of-construct' renamed to 'no-construct-in-public-property' in v4. ↓

fix Use 'awscdk/no-construct-in-public-property' instead.

Install

npm install eslint-plugin-awscdk

yarn add eslint-plugin-awscdk

pnpm add eslint-plugin-awscdk

Imports

default (cdkPlugin)
wrong
```
const cdkPlugin = require('eslint-plugin-awscdk');
```
correct
```
import cdkPlugin from 'eslint-plugin-awscdk';
```
Plugin is ESM-first. Use import syntax. CommonJS require works but is not recommended; if used, you may need dynamic import or a CJS wrapper.
configs.recommended
wrong
```
require('eslint-plugin-awscdk/configs/recommended')
```
correct
```
cdkPlugin.configs.recommended
```
Config objects are exported under cdkPlugin.configs. Do not use separate path imports; they are not guaranteed to exist.
rules (e.g., 'awscdk/require-jsdoc')
wrong
```
"@awscdk/require-jsdoc": "warn"
```
correct
```
"awscdk/require-jsdoc": "warn"
```
Rule names are prefixed with 'awscdk/', not '@awscdk/'. Common mistake when copy-pasting from other plugins.

Quickstart

Shows flat ESLint config using the plugin with typescript-eslint, extending the recommended config and adding a custom rule.

// eslint.config.mjs
import eslint from "@eslint/js";
import { defineConfig } from "eslint/config";
import tseslint from "typescript-eslint";
import cdkPlugin from "eslint-plugin-awscdk";

export default defineConfig([
  {
    files: ["lib/**/*.ts", "bin/*.ts"],
    extends: [
      eslint.configs.recommended,
      ...tseslint.configs.recommended,
      cdkPlugin.configs.recommended,
    ],
    rules: {
      "awscdk/require-jsdoc": "warn",
    },
  },
]);