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 |