typescript-eslint - Quick Reference

When to Use This Skill

Configure ESLint for TypeScript projects
Type-aware rules for TypeScript
Migration from TSLint

When NOT to Use This Skill

Full ESLint 9 setup - Use eslint-biome skill for complete configuration
Biome linter - Use eslint-biome skill for Biome setup
Code quality principles - Use quality-common for SOLID/Clean Code
Java/Kotlin - Use sonarqube skill for JVM languages

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: typescript-eslint for comprehensive documentation.

Basic Setup

npm install -D eslint typescript-eslint

Flat Config (ESLint 9+)

eslint.config.mjs

import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';

export default tseslint.config(
  eslint.configs.recommended,
  ...tseslint.configs.recommended,
);

Type-Aware Linting

import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';

export default tseslint.config(
  eslint.configs.recommended,
  ...tseslint.configs.recommendedTypeChecked,
  {
    languageOptions: {
      parserOptions: {
        projectService: true,
        tsconfigRootDir: import.meta.dirname,
      },
    },
  },
);

Strict Configuration

export default tseslint.config(
  eslint.configs.recommended,
  ...tseslint.configs.strictTypeChecked,
  ...tseslint.configs.stylisticTypeChecked,
);

Common Rules

{
  rules: {
    // Prevent unused variables
    '@typescript-eslint/no-unused-vars': ['error', {
      argsIgnorePattern: '^_'
    }],

    // Require explicit return types
    '@typescript-eslint/explicit-function-return-type': 'warn',

    // Prevent any usage
    '@typescript-eslint/no-explicit-any': 'error',

    // Require await in async functions
    '@typescript-eslint/require-await': 'error',

    // Prevent floating promises
    '@typescript-eslint/no-floating-promises': 'error',

    // Consistent type imports
    '@typescript-eslint/consistent-type-imports': 'error',
  }
}

File-Specific Rules

export default tseslint.config(
  // ... base config
  {
    files: ['**/*.test.ts', '**/*.spec.ts'],
    rules: {
      '@typescript-eslint/no-explicit-any': 'off',
    },
  },
  {
    files: ['**/*.js'],
    ...tseslint.configs.disableTypeChecked,
  },
);

Anti-Patterns

Anti-Pattern	Why It's Bad	Correct Approach
Not using type-aware rules	Misses Promise, async issues	Use `recommendedTypeChecked`
Allowing `any` everywhere	Defeats TypeScript purpose	Set `no-explicit-any: error`
No `require-await` rule	Unnecessary async keywords	Enable type-aware async rules
Type checking JS files	JS has no types	Use `disableTypeChecked` for .js
Disabling rules in test files	Tests need quality too	Only disable `no-explicit-any` if needed
Ignoring unused variables	Code smell, unused imports	Use `no-unused-vars` with ignore pattern

Quick Troubleshooting

Issue	Likely Cause	Solution
Type-aware rules not working	Missing `projectService: true`	Add to languageOptions.parserOptions
Linting very slow	Type checking all files	Limit type rules to `*/.ts` only
"Unsafe" errors everywhere	Strict type checking	Use `strictTypeChecked` or disable specific rules
Promise errors not caught	Missing `no-floating-promises`	Enable in recommendedTypeChecked preset
Unused imports not detected	Wrong rule configuration	Use `@typescript-eslint/no-unused-vars`
Rules conflict with Prettier	Both formatting code	Add `eslint-config-prettier` last