Setting up ESLint in AWS CDK

Introduction

In this article, I will introduce how to set up ESLint in a CDK project.

This article is intended for CDK projects written in TypeScript.

What is ESLint?

First of all, what is ESLint?

ESLint is a tool that analyzes code in JavaScript, TypeScript, etc., to detect simple syntax errors or code that violates coding conventions.

By using this tool, you can unify coding conventions (coding style) among team members.

https://eslint.org/

1. Installing ESLint

Now, let me introduce the steps to set up ESLint in a CDK project.

First, run the following command to install the necessary packages.
(This time, we will install ESLint and the TypeScript plugin for ESLint.)

# npm
npm install -D eslint typescript-eslint

# yarn
yarn add -D eslint typescript-eslint

# pnpm
pnpm install -D eslint typescript-eslint

Since ESLint v8 and below are currently EOL (End Of Life), please make sure to install v9.

2. Configuring package.json

Next, add the lint command to scripts in package.json so that you can run the ESLint command from the terminal.
(Adding the --fix option applies automatic fixes.)

package.json

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

3. Creating the ESLint configuration file

Next, create eslint.config.mjs in the root of your project.

eslint.config.mjs

import eslint from "@eslint/js";
import tsEslint from "typescript-eslint";

export default tsEslint.config(
  // Apply recommended ESLint settings
  eslint.configs.recommended,
  ...tsEslint.configs.recommended,
  {
    // Target TypeScript files under the lib and bin directories
    files: ["lib/**/*.ts", "bin/*.ts"],
    languageOptions: {
      parserOptions: {
        projectService: true,
        project: "./tsconfig.json",
      },
    },
    plugins: {},
    rules: {},
  },
  // Specify files and directories to ignore
  {
    ignores: ["cdk.out", "node_modules", "*.js"],
  }
);

4. Installing the Editor Extension

Finally, install the extension so that code violating the rules set in ESLint can be visualized on the editor (for VSCode).
Basic setup is complete at this point (Easy!!)

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

Also, add the following content to .vscode/settings.json:

.vscode/settings.json

{
+ "eslint.useFlatConfig": true,
 ...
}

Verifying the Operation

Now that the basic setup is complete, verify the operation using the following steps:

1. Include code that violates the rules, like the following, in a file under the lib directory in advance:

lib/my-stack.ts

const a:any = ""

2. Run the following command to verify if the relevant part results in an error:

# npm
npm run lint

# yarn
yarn lint

# pnpm
pnpm lint

Troubleshooting

An error appears in the terminal, but not in the editor

If you face such an issue, measures like reviewing the extension version or reloading (or restarting) the editor may be effective (since it is an editor-side issue).

No error appears in the terminal

If you face such an issue, running npm run lint --debug to check if ESLint is functioning normally can be effective.

For more details, please refer to the following documentation:

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

Customizing Rules

In the eslint.config.mjs above, we adopted the recommended rules.
If there are rules among them that you don't want to trigger errors, or rules not included there but you want them to trigger errors, you can solve this by customizing the ESLint rules.

Changing Rules

For example, if you want to "avoid errors even if there are unused variables," modify the configuration file as follows:

eslint.config.mjs

import eslint from "@eslint/js";
import tsEslint from "typescript-eslint";

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

Installing Plugins

ESLint has a useful plugin for CDK called eslint-plugin-awscdk, which allows you to apply the following rules:

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

Rules regarding naming conventions

Description	Included in recommended rules
Specify 'scope, id' or 'scope, id, props' for the constructor properties of a Construct	✅
Do not add suffixes such as "Construct" or "Stack" to the Construct ID	✅
Do not include the parent Construct's name in the Construct ID	✅
Do not use variables for the Construct ID	✅
Write the Construct ID in PascalCase	✅
Construct Props should be written in the format ${ConstructName}Props

Rules regarding safety

Description	Included in recommended rules
Add "readonly" to properties of Props (Interface)	✅
Add "readonly" to public variables of the Construct	✅
Do not specify a Construct type for Props properties	✅
Do not specify a Construct type for Construct public properties	✅
Always pass this to the second argument (scope property) of the Construct constructor	✅

Rules regarding module structure

Description	Included in recommended rules
Do not call modules inside the private directory from the outside

Rules regarding comments

Description	Included in recommended rules
Write JSDoc for properties of Props (Interface) and public properties of the Construct
Write '@default' JSDoc for optional properties of Props (Interface)

Plugin Installation Steps

The procedure for installing eslint-plugin-awscdk is as follows:

1. Installing the plugin

# npm
npm install -D eslint-plugin-awscdk

# yarn
yarn add -D eslint-plugin-awscdk

# pnpm
pnpm install -D eslint-plugin-awscdk

2. Updating 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(
  // Apply recommended ESLint settings
  eslint.configs.recommended,
  ...tsEslint.configs.recommended,
  {
    // Target TypeScript files under the lib and bin directories
    files: ["lib/**/*.ts", "bin/*.ts"],
+   extends: [cdkPlugin.configs.recommended],
    // ...Other settings
  },
);

Summary

In this article, I introduced how to set up ESLint in a CDK project.

By introducing ESLint, you can expect improved code quality and more efficient team development.
Especially by using eslint-plugin-awscdk, you will be able to automatically check for CDK-specific best practices as well.

Let's master ESLint and have a comfortable CDK development experience!!

Documentation

ESLint Documentation

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

typescript-eslint Documentation

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

eslint-plugin-awscdk Documentation (Japanese)

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