Mastering ESLint: From Quick Setup to Advanced Rule Customization

Introduction

Code error checking and automatic formatting are familiar to developers, but inconsistencies in formatting rules across a project can cause noisy diffs and block code reviews. This article introduces ESLint, the tool that powers automatic code checks and formatting.

What is ESLint?

ESLint is a JavaScript linting tool that detects syntax errors and enforces code style. It improves code quality by defining usage conventions and helps maintain a consistent code format.

JS linting tools have evolved through three milestones: JSLint, JSHint, and ESLint.

Basic Usage

Initialization

Run npx eslint --init to answer a series of prompts (environment, framework, TypeScript, style preferences) and generate a configuration file.

# Install as a dev dependency
npm install eslint --save-dev
# Initialize
npx eslint --init

After initialization, an .eslintrc.{js,yml,json} file is created at the project root.

Configuration

Below is an example JSON configuration highlighting key sections:

{
  "env": {
    "browser": true,
    "es2021": true
  },
  "parserOptions": {
    "ecmaVersion": 12,
    "sourceType": "module",
    "ecmaFeatures": { "jsx": true }
  },
  "plugins": ["@typescript-eslint"],
  "extends": ["eslint:recommended"],
  "rules": {
    "quotes": ["error", "double"],
    "prefer-const": "error",
    "@typescript-eslint/consistent-type-definitions": ["error", "interface"]
  },
  "globals": { "$": "readonly" }
}

Environment and globals : The no-undef rule warns about undefined variables; you can define globals via the env and globals fields.

Rules : Rules are defined in the rules section. Each rule can be set to "off", "warn", or "error", or an array where the first element is the severity and the rest are options.

Parser : ESLint uses parserOptions to specify language features. For TypeScript, set parser": "@typescript-eslint/parser" and install the corresponding plugin.

Plugins : Custom rules can be added via plugins. For example, to use @typescript-eslint rules, add it to the plugins array and configure the desired rules.

Extends : The extends field allows you to inherit shared configurations, such as eslint:recommended or plugin:prettier/recommended.

Principles

AST (Abstract Syntax Tree)

ESLint parses source code into an AST using the espree parser. Rules operate by traversing this tree and checking nodes against selectors.

AST is also the foundation for tools like Babel and Webpack.

How Rules Work

Each rule exports a meta object (metadata) and a create function that returns callbacks for AST node selectors. During traversal, ESLint triggers these callbacks to report problems.

module.exports = {
  meta: { type: "problem", docs: { description: "disallow `debugger`" } },
  create(context) {
    return { DebuggerStatement(node) { context.report({ node, messageId: "unexpected" }); } };
  }
};

The engine builds an event emitter from all rule listeners, walks the node queue, and collects linting problems.

Integration with Other Tools

VSCode

Install the ESLint extension and enable auto‑fix on save via "editor.codeActionsOnSave": { "source.fixAll.eslint": true }.

Prettier

Prettier handles code formatting while ESLint focuses on code quality. Use eslint-config-prettier to disable conflicting ESLint rules and optionally add eslint-plugin-prettier to report formatting issues as ESLint errors.

{
  "extends": ["prettier"]
}

Husky

Husky can run ESLint before commits to prevent bad code from entering the repository.

{
  "husky": { "hooks": { "pre-commit": "eslint src/** --fix" } }
}

lint‑staged

lint‑staged runs ESLint only on staged files, improving performance for large projects.

{
  "lint-staged": { "*.{js,ts}": ["npx eslint --fix"] }
}

Conclusion

The article covered ESLint’s core configuration, rule mechanics, and how to combine it with VSCode, Prettier, Husky, and lint‑staged to enforce consistent, high‑quality JavaScript code across a team.