eslint-cdk-plugin

3.4.9 verified Sat Apr 25 auth: no javascript

ESLint plugin for AWS CDK projects that enforces best practices and prevents common mistakes. Current stable version is 3.4.9. It is being renamed to eslint-plugin-awscdk starting from v4.0.0 to follow ESLint's naming convention. The package provides lint rules specific to CDK constructs, such as preventing construct ID collisions, ensuring proper use of stacks, and avoiding constructs in interfaces. It requires Node.js ^18.18.0 || ^20.9.0 || >=21.1.0, ESLint ^8.57.0 || ^9.0.0 || ^10.0.0, and TypeScript >=4.8.4 <6.1.0. Ships TypeScript types. Key differentiators: type-aware rules for CDK constructs, migration path from old package name, recommended config integration with typescript-eslint.

Common errors

error ESLint: Error: Failed to load plugin 'eslint-cdk-plugin': Cannot find module 'eslint-cdk-plugin' ↓

cause Package not installed or incorrect import path.

fix

Run npm install -D eslint-cdk-plugin and ensure version 3.x is installed.

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

cause Incorrect import of the plugin object; using default export as an object without 'default'.

fix

Use import cdkPlugin from 'eslint-cdk-plugin' (ESM) or const cdkPlugin = require('eslint-cdk-plugin').default (CJS if supported).

error Parsing error: The 'import' keyword is not supported in the current configuration. ↓

cause ESLint config is not set up for ES module syntax.

fix

Set "type": "module" in package.json or rename config file to eslint.config.mjs.

error Error: Cannot find module 'typescript-eslint' ↓

cause typescript-eslint is not installed, but required by the plugin.

fix

npm install -D typescript-eslint

error Error: No matching configuration found for 'lib/**/*.ts' ↓

cause Flat config files pattern does not match any files in the project.

fix

Adjust the files array in the ESLint config to match your project's CDK source directory (e.g., ['src/**/*.ts']).

Warnings

breaking Package renamed from eslint-cdk-plugin to eslint-plugin-awscdk in v4.0.0. ↓

fix Uninstall old package, install new one, and use the migration script: npm uninstall eslint-cdk-plugin && npm install -D eslint-plugin-awscdk && npx migrate-cdk-plugin

gotcha Plugin requires typescript-eslint for type-aware rules. Missing it will cause runtime errors on type-dependent rules. ↓

fix Install typescript-eslint and configure parserOptions.projectService in your ESLint config.

deprecated Legacy eslintrc format ( .eslintrc ) is not supported in v3+. ↓

fix Migrate to flat config (eslint.config.mjs) using defineConfig or equivalent.

gotcha The plugin's TypeScript version peer requirement is <6.1.0. Using TypeScript >=6.1.0 will cause peer dep conflicts or runtime errors. ↓

fix Downgrade TypeScript to <6.1.0 or wait for an update that broadens the range.

breaking ESLint v8 support removed in v4.0.0; only ESLint v9+ is supported. ↓

fix Upgrade ESLint to v9 or higher, or pin plugin to v3.x.

deprecated The old package name eslint-cdk-plugin will stop receiving updates after a while and will be deprecated. ↓

fix Migrate to eslint-plugin-awscdk as soon as possible.

Install

npm install eslint-cdk-plugin

yarn add eslint-cdk-plugin

pnpm add eslint-cdk-plugin

Imports

eslint-cdk-plugin
wrong
```
const cdkPlugin = require('eslint-cdk-plugin')
```
correct
```
import cdkPlugin from 'eslint-cdk-plugin'
```
ESM-only since v3. Requires flat config (eslint.config.mjs). For require, use dynamic import or upgrade to v4 with eslint-plugin-awscdk.
cdkPlugin
wrong
```
import cdkPlugin from 'eslint-plugin-awscdk'
```
correct
```
import cdkPlugin from 'eslint-cdk-plugin'
```
For v3.x, use old package name. v4+ uses eslint-plugin-awscdk. Ensure correct import to avoid 'plugin not found' errors.
cdk
wrong
```
plugins: { cdk: cdkPlugin.configs.recommended }
```
correct
```
plugins: { cdk: cdkPlugin }
```
refer to the plugin object itself, not its config, when setting up custom rules.
cdkPlugin.configs.recommended
wrong
```
extends: ['cdkPlugin.configs.recommended']
```
correct
```
extends: [cdkPlugin.configs.recommended]
```
config is an object, not a string. Use object spread or reference directly.

Quickstart

Sets up flat config with recommended CDK rules using typescript-eslint. Files scope limits to CDK sources.

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

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