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 |
