eslint-config

When to Use

• Setting up ESLint from scratch using the modern flat config format (eslint.config.js).
• Migrating a project from legacy .eslintrc.* to flat config.
• Configuring TypeScript-ESLint for strict type-checked linting.
• Writing custom ESLint rules or shareable config packages.
• Resolving rule conflicts between ESLint, Prettier, and framework-specific plugins.
• Optimizing linting performance for large monorepos.

Critical Patterns

• Flat Config Only: Always use eslint.config.js (or .mjs/.mts). The legacy .eslintrc.* format is deprecated since ESLint v9. Do NOT create new projects with .eslintrc.
• Explicit Over Implicit: Flat config has no implicit inheritance. Every config object in the array is applied in order — later entries override earlier ones.
• TypeScript Requires Parser: Always pair @typescript-eslint/parser with @typescript-eslint/eslint-plugin. Use type-checked rules (strictTypeChecked) for maximum safety.
• Severity Consistency: Use "error" for rules that must block CI, "warn" for progressive adoption, and "off" to explicitly disable inherited rules. Never leave rules ambiguous.
• Ignore via Config: Use the ignores property in flat config instead of .eslintignore files. Global ignores go in a config object with only the ignores key.
• Plugin Namespacing: In flat config, plugins are objects, not strings. Import the plugin and assign it to a namespace key to avoid collisions.
• Performance: Use --cache in CI and locally. For monorepos, scope linting to changed files with --no-error-on-unmatched-pattern.

Code Examples

Modern Flat Config (eslint.config.js)

import js from "@eslint/js";
import tseslint from "typescript-eslint";
import prettier from "eslint-config-prettier";

export default tseslint.config(
  // Global ignores — standalone object with ONLY ignores key
  {
    ignores: ["dist/", "node_modules/", "coverage/", "**/*.generated.*"],
  },

  // Base JS recommended rules
  js.configs.recommended,

  // TypeScript strict + type-checked rules
  ...tseslint.configs.strictTypeChecked,
  ...tseslint.configs.stylisticTypeChecked,

  // TypeScript parser options — applies to all TS files
  {
    languageOptions: {
      parserOptions: {
        projectService: true,
        tsconfigRootDir: import.meta.dirname,
      },
    },
  },

  // Disable type-checked rules for JS files (config files, scripts)
  {
    files: ["**/*.js", "**/*.mjs"],
    ...tseslint.configs.disableTypeChecked,
  },

  // Project-specific overrides
  {
    files: ["src/**/*.ts"],
    rules: {
      "@typescript-eslint/no-unused-vars": [
        "error",
        { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
      ],
      "@typescript-eslint/explicit-function-return-type": "error",
      "@typescript-eslint/no-floating-promises": "error",
      "@typescript-eslint/strict-boolean-expressions": "warn",
    },
  },

  // Test file relaxations
  {
    files: ["**/*.test.ts", "**/*.spec.ts"],
    rules: {
      "@typescript-eslint/no-explicit-any": "off",
      "@typescript-eslint/no-non-null-assertion": "off",
      "@typescript-eslint/no-unsafe-assignment": "off",
    },
  },

  // Prettier must be LAST to override formatting rules
  prettier,
);