Eslint

ESLint Best Practices

Provides guidance for configuring ESLint using the modern flat config format (eslint.config.js), selecting and tuning rules, managing plugins, and integrating linting into CI/CD workflows.

Core Concepts

• Flat config (eslint.config.js) is the current standard. The legacy .eslintrc.* format is deprecated as of ESLint v9.
• Configuration objects are merged in order — later objects override earlier ones for the same rule.
• Rule severities: "off" (0) | "warn" (1) | "error" (2).
• Plugins extend ESLint with additional rules, processors, and languages. Reference as pluginName/ruleName.

Setup

Quick initialization (recommended)

npm init @eslint/config@latest

This generates eslint.config.js interactively. Requires Node.js ^20.19.0, ^22.13.0, or >=24.

Manual setup

npm install --save-dev eslint@latest @eslint/js@latest

Create eslint.config.js:

import { defineConfig } from "eslint/config";
import js from "@eslint/js";

export default defineConfig([
  {
    files: ["**/*.js"],
    plugins: { js },
    extends: ["js/recommended"],
    rules: {
      "no-unused-vars": "warn",
      "no-undef": "error",
    },
  },
]);

Run linting:

npx eslint src/

Flat Config Structure

Every configuration object accepts these keys:

File targeting

// Apply rules only to source files
{ files: ["src/**/*.{js,ts}"], rules: { ... } }

// Apply rules to all except tests
{ files: ["**/*.js"], ignores: ["**/*.test.js"], rules: { ... } }

Global ignores (use globalIgnores)

import { defineConfig, globalIgnores } from "eslint/config";

export default defineConfig([
  globalIgnores(["dist/", "coverage/", "*.min.js"]),
  // other config objects...
]);

Use globalIgnores() — not bare ignores keys — for project-wide exclusions. This is the clearest and least error-prone pattern.

Import .gitignore patterns

import { includeIgnoreFile } from "@eslint/compat";
import { fileURLToPath } from "node:url";

const gitignorePath = fileURLToPath(new URL(".gitignore", import.meta.url));

export default defineConfig([
  includeIgnoreFile(gitignorePath),
  // ...
]);

Rule Configuration Best Practices

Prefer "error" for enforced standards

Use "error" for rules that block bad code from merging. Reserve "warn" for violations that require human judgment or incremental adoption.

rules: {
  "no-var": "error",          // always use const/let
  "prefer-const": "error",    // enforce immutability where possible
  "eqeqeq": ["error", "always"], // ban == in favor of ===
  "no-console": "warn",       // flag but don't block during development
}

Disable inline comments sparingly

Use // eslint-disable-next-line rule-name -- reason with a mandatory reason. Never disable wholesale with /* eslint-disable */ without scoping and justification.

// eslint-disable-next-line no-console -- CLI entrypoint needs output
console.log("Starting server...");

Enable detection of stale disable comments:

linterOptions: {
  reportUnusedDisableDirectives: "error",
}

File-pattern overrides instead of inline disables

Disable rules for test files via configuration, not inline comments:

{
  files: ["**/*.test.{js,ts}", "**/*.spec.{js,ts}"],
  rules: {
    "no-unused-expressions": "off", // chai/jest assertions
  },
}

Plugin Usage

Register and use a plugin

import jsdoc from "eslint-plugin-jsdoc";
import { defineConfig } from "eslint/config";

export default defineConfig([
  {
    files: ["**/*.js"],
    plugins: { jsdoc },
    rules: {
      "jsdoc/require-description": "error",
      "jsdoc/check-values": "error",
    },
  },
]);

The plugin namespace is the property name in plugins. Convention: strip the eslint-plugin- prefix.

Extend a plugin's recommended config

import react from "eslint-plugin-react";
import { defineConfig } from "eslint/config";

export default defineConfig([
  {
    files: ["**/*.{jsx,tsx}"],
    plugins: { react },
    extends: ["react/recommended"],
    languageOptions: {
      parserOptions: { ecmaFeatures: { jsx: true } },
    },
  },
]);

TypeScript Support

Install the TypeScript parser and plugin:

npm install --save-dev typescript-eslint

import tseslint from "typescript-eslint";
import { defineConfig } from "eslint/config";

export default defineConfig([
  ...tseslint.configs.recommended,
  {
    files: ["**/*.ts", "**/*.tsx"],
    rules: {
      "@typescript-eslint/no-explicit-any": "warn",
      "@typescript-eslint/explicit-function-return-type": "off",
    },
  },
]);

Linter Options

{
  linterOptions: {
    noInlineConfig: false,                    // allow inline eslint comments
    reportUnusedDisableDirectives: "error",   // fail on stale disables
    reportUnusedInlineConfigs: "warn",        // warn on redundant inline configs
  },
}

Debugging Configuration

Inspect which config objects apply to a file:

npx eslint --inspect-config        # Opens config inspector UI
npx eslint --print-config file.js  # Prints merged config for a file

CI/CD Integration

Add to package.json:

{
  "scripts": {
    "lint": "eslint src/",
    "lint:fix": "eslint src/ --fix"
  }
}

Run npm run lint in CI. ESLint exits with code 1 when any "error"-severity rule triggers, blocking merges.

Quick Reference: Rule Severity

Additional Resources

Reference Files

• references/configuration-guide.md — Detailed flat config patterns, cascading, TypeScript config files, monorepo setup
• references/rules-and-plugins.md — Commonly used rules reference and popular plugin ecosystem

Example Files

• examples/eslint.config.js — Production-ready config for a TypeScript project with React