What it is
typescript-eslint lets ESLint parse and lint TypeScript, including rules that use full type information to catch bugs a syntax-only linter cannot see.
Provides a parser, a plugin of TypeScript-specific rules, and shared configs. Type-aware rules require pointing the parser at your tsconfig, which costs build time but catches far more.
Installation
npm install -D typescript-eslint eslint typescriptGetting started
The smallest useful thing you can do with it, and what each part means.
import tseslint from 'typescript-eslint';
export default tseslint.config(
...tseslint.configs.recommendedTypeChecked,
{
languageOptions: {
parserOptions: {
projectService: true, // enables type information
tsconfigRootDir: import.meta.dirname,
},
},
rules: {
'@typescript-eslint/no-floating-promises': 'error',
'@typescript-eslint/no-explicit-any': 'warn',
},
},
);Advanced usage
Where the library earns its place over a simpler alternative.
// no-floating-promises — an unhandled rejection waiting to happen
saveUser(user); // error: promise not awaited or handled
void saveUser(user); // explicit fire-and-forget is allowed
// no-misused-promises — an async callback where void is expected
button.addEventListener('click', async () => { await save(); }); // flagged
// await-thenable — awaiting something that is not a promise
const x = await getSyncValue(); // flagged as pointless
// no-unnecessary-condition — a check that can never be false
if (definitelyDefined) { } // flagged using the real typeErrors and fixes
The failures you are most likely to hit, and what actually resolves them.
- Parsing error: file was not found by the project service
- The file is outside tsconfig's include. Add it, or use a separate config block without type-aware rules for that path.
- Linting became very slow
- Type-aware rules build a program. Narrow the linted file set and make sure you are not linting node_modules or dist.
Best practices
- Enable recommendedTypeChecked, not just recommended — the type-aware rules are the value.
- Turn on no-floating-promises; unhandled rejections are among the most common Node bugs.
- Exclude generated code and build output from linting to keep runs fast.
- Use `void` to mark deliberate fire-and-forget calls rather than disabling the rule.
Background
Why it exists, and what it was reacting to.
It replaced the abandoned TSLint after the TypeScript team decided ESLint should be the ecosystem's single linter. Its type-aware rules are the feature that makes it more than a parser.