eslint

eslint Best Practices

ESLint is the bedrock of our JavaScript and TypeScript code quality. This guide outlines our definitive, opinionated approach to configuring and using ESLint, focusing on modern best practices for December 2025.

1. Core Configuration: Flat Config is Mandatory

Always use the new flat configuration format (eslint.config.js, .mjs, .cjs, or .ts). The legacy .eslintrc format is deprecated and must not be used.

1.1. Base Configuration

Start with the recommended and strict presets for robust error prevention and stylistic consistency.

// eslint.config.js
import eslint from '@eslint/js';
import { defineConfig } from 'eslint/config';

export default defineConfig([
  eslint.configs.recommended, // Essential base rules
  eslint.configs.strict,     // Stricter error-prevention rules
  eslint.configs.stylistic,  // Stylistic rules (handled by Prettier, see 1.3)
  // ... other configs and rules
]);

1.2. TypeScript Integration (Type-Aware Linting)

For TypeScript projects, enable type-aware linting. This provides powerful, deep analysis that catches subtle type-related issues.

// eslint.config.ts (requires `jiti` or `ts-node` for execution)
import eslint from '@eslint/js';
import { defineConfig } from 'eslint/config';
import tseslint from 'typescript-eslint';

export default defineConfig([
  eslint.configs.recommended,
  tseslint.configs.recommendedTypeChecked, // TypeScript recommended rules with type-checking
  tseslint.configs.strictTypeChecked,      // Stricter TypeScript rules with type-checking
  tseslint.configs.stylisticTypeChecked,   // TypeScript stylistic rules (handled by Prettier)
  {
    languageOptions: {
      parser: tseslint.parser,
      parserOptions: {
        projectService: true, // Enable TypeScript's project service for type info
        tsconfigRootDir: import.meta.dirname, // Point to your project root
      },
    },
    files: ['**/*.ts', '**/*.tsx', '**/*.mts', '**/*.cts'], // Apply to TS files
  },
  // ... other configs and rules
]);