skip to content

TypeScript Integration

Linting TypeScript with typescript-eslint: its parser, typed presets like recommendedTypeChecked, and projectService supplying types. Asked because typed rules catch floating promises tsc misses.

on this pageshow

questions

5

Why can't ESLint lint a TypeScript file with its default parser, and what does the typescript-eslint package add so that it can?

level: juniorimportance: must knowfreq 28%

answer

  1. rules walk a tree, not text
  2. the built-in parser reads JavaScript only
  3. a type annotation stops the parse
  4. parser, plugin and configs in one package
  5. the preset sets languageOptions.parser for you

basics

~20 s

ESLint's default parser, Espree, reads only JavaScript, so a type annotation is a parsing error. The typescript-eslint package adds a parser that turns TypeScript into ESLint's tree format, a plugin of TypeScript rules, and presets that wire both in.

solid answer

~40 s

ESLint never reads source text directly: a **parser** turns each file into an ESTree-shaped syntax tree, and rules walk that tree. The built-in parser, Espree, parses JavaScript only, so `let total: number = 0;` fails as a parsing error before any rule runs. The `typescript-eslint` package provides three things: `@typescript-eslint/parser`, which turns TypeScript into an ESTree-compatible tree; `@typescript-eslint/eslint-plugin`, the rules under the `@typescript-eslint/` prefix; and `configs` such as `tseslint.configs.recommended`. Those presets already set `languageOptions.parser`, register the plugin and add an object that matches `.ts`, `.tsx`, `.mts` and `.cts` files, so most configs never name the parser by hand. The `typescript` package must be installed as well, because the parser loads it even when no rule uses type information.

code

javascript · 8 lines
javascript
// eslint.config.mjs
import js from '@eslint/js';
import tseslint from 'typescript-eslint';

export default [
  js.configs.recommended,
  ...tseslint.configs.recommended,
];

go deeper

for a junior

Recall the chain: parser, then syntax tree, then rules. ESLint's own parser reads JavaScript only, so TypeScript needs typescript-eslint's parser, and its presets bring the rules.

for a middle

Explain what the recommended preset actually contains: the base object with parser and plugin namespace, the object that turns off compiler-covered core rules for TypeScript files, and the rule set with its extension-rule swaps.

for a senior

Show you can diagnose a half-wired config: parser set but no rules, no-undef misfiring on global types, a files pattern that never reaches .ts files, or a missing typescript dependency.

for a principal

Frame typescript-eslint as a layer beside the compiler, not instead of it: syntax rules cost little, typed rules cost a project build, and a team should choose that cost deliberately.

## What a parser does for ESLint ESLint never inspects raw source text. For every file it lints, a **parser** turns the text into an **abstract syntax tree (AST)** in the ESTree format, ESLint runs scope analysis over that tree, and each enabled rule visits the nodes it cares about. The parser therefore decides what syntax ESLint can read at all. ESLint's built-in parser is **Espree**, and it parses JavaScript only. A line such as `let total: number = 0;` is not valid JavaScript because of the `: number` annotation, so Espree raises an error and ESLint reports the file with a **parsing error** instead of running its rules. Interfaces, generics, `enum` declarations and `as` casts fail the same way. TypeScript's own compiler has a parser, but its tree has a different shape: it is optimised for type checking and for parsing incomplete code while you type, and it represents many nodes differently from ESTree. ESLint rules cannot walk it directly, which is why a conversion layer is needed. ## What the typescript-eslint package contains The `typescript-eslint` package is the single entry point. It re-exports the pieces that older setups installed one by one: | Export | Re-export of | What it does | |---|---|---| | `tseslint.parser` | `@typescript-eslint/parser` | Parses TypeScript into ESTree-compatible nodes and can supply TypeScript programs to typed rules | | `tseslint.plugin` | `@typescript-eslint/eslint-plugin` | The rules, all named with the `@typescript-eslint/` prefix | | `tseslint.configs` | shared flat configs | Presets such as `recommended`, `strict`, `stylistic`, their `TypeChecked` versions, and `disableTypeChecked` | Install it beside ESLint and TypeScript: ```bash npm install --save-dev eslint @eslint/js typescript typescript-eslint ``` `typescript` is a peer dependency, not an optional extra: the parser loads it even when no rule uses type information. typescript-eslint 8.71.1 declares TypeScript `>=4.8.4 <6.1.0` and ESLint `^8.57.0 || ^9.0.0 || ^10.0.0` as its peer ranges. ## Wiring it into a flat config ```js // eslint.config.mjs import js from '@eslint/js'; import tseslint from 'typescript-eslint'; export default [ js.configs.recommended, ...tseslint.configs.recommended, ]; ``` `tseslint.configs.recommended` is an array, which is why it is spread. It holds three configuration objects: 1. **base** sets `languageOptions.parser` to the typescript-eslint parser, sets `sourceType: 'module'` and registers the plugin under the `@typescript-eslint` namespace. 2. **eslint-recommended** matches `.ts`, `.tsx`, `.mts` and `.cts` files, turns off core rules the TypeScript compiler already enforces (`no-undef`, `no-redeclare`, `no-dupe-class-members` and others) and turns on `no-var`, `prefer-const`, `prefer-rest-params` and `prefer-spread`. 3. **recommended** enables the rules themselves, for example `@typescript-eslint/no-explicit-any`, and swaps some core rules for TypeScript-aware extensions: core `no-unused-vars` goes off and `@typescript-eslint/no-unused-vars` comes on. Because the preset sets the parser, most projects never write `languageOptions.parser` themselves. You set it by hand only when you assemble a config without the presets. ## Which files get linted ESLint lints `**/*.js`, `**/*.cjs` and `**/*.mjs` by default; any other extension is linted only when a configuration object's `files` pattern matches it. The preset's second object matches the TypeScript extensions, so `npx eslint .` reaches `.ts` files once the preset is in place. If you scope your own object with `files`, include the TypeScript extensions in it, or your own rules will not reach those files. ## Choosing a starting preset The untyped presets are not one ladder, and picking among them is a team decision: - **`recommended`**: rules whose reports are almost always a bug or bad practice, safe to drop in without extra configuration. Rule additions and removals wait for a major release. - **`strict`**: everything in `recommended` plus more opinionated rules that can also catch bugs. typescript-eslint suggests it only when a good share of the team is proficient in TypeScript, and it is not covered by semantic versioning, so its rules can change outside a major release. - **`stylistic`**: rules for consistent, simpler code that do not change program logic. It **adds** to `recommended` or `strict`; it does not replace either. Rules you set in your own `rules` object, after the preset, take precedence, so a preset is a starting point you can tune rather than a contract. ## Parsing is not type checking - The parser reads **syntax**. The `recommended` preset needs no `tsconfig.json` and lints each file on its own. - **Type information** is opt-in: rules such as `@typescript-eslint/no-floating-promises` need `parserOptions.projectService` and live in the `TypeChecked` presets. - typescript-eslint does not report type errors. A wrong argument type is still the compiler's job; the linter adds checks the compiler does not make. ## Mistakes worth recognising - **Setting only `languageOptions.parser`.** Files now parse, but no TypeScript rules run, and if `js.configs.recommended` is on, core `no-undef` keeps running on TypeScript files and can report global types, such as those from `@types` packages, as undefined. The preset would have switched `no-undef` off for TypeScript files. - **Installing `@typescript-eslint/parser` and `@typescript-eslint/eslint-plugin` separately** and wiring them by hand. It works, but the `typescript-eslint` package already depends on both. - **Leaving out the `typescript` package**, which the parser needs at startup. - **Expecting the untyped preset to catch async mistakes.** Rules that need types belong to the `TypeChecked` presets and their parser options.

  • Does tseslint.configs.recommended need a tsconfig.json?
    No. The untyped presets parse each file on its own and use no type information, so no `tsconfig.json` is read. Only rules that need types, collected in `recommendedTypeChecked`, `strictTypeChecked` and `stylisticTypeChecked`, require `languageOptions.parserOptions.projectService` (or the older `project`), and that is when typescript-eslint starts asking TypeScript about the project.
  • Why does the recommended preset turn off core no-unused-vars and turn on @typescript-eslint/no-unused-vars?
    Core rules know nothing of the features TypeScript adds, so some of them misbehave on TypeScript code. The typescript-eslint version is an extension rule: it extends the core rule with support for TypeScript features such as types. typescript-eslint's documented way to use one is to turn the base rule off and the extension on, which is exactly what the preset does.
  • Can typescript-eslint lint plain JavaScript files?
    Yes. Its rules run on JavaScript files when a config object's `files` matches them, and many are useful there; rules that match only TypeScript syntax, such as `no-explicit-any`, simply never report. The `typescript` package is still required, because the parser loads TypeScript either way.

  • ESLint has parsed TypeScript natively ever since flat config arrived.
  • Pointing languageOptions.parser at the TypeScript parser also turns on the TypeScript rules.
  • typescript-eslint replaces the compiler, so type errors now show up as lint errors.
  • Every typescript-eslint preset needs a tsconfig.json before it can run.
  • The typescript package is optional when you only lint and never compile.
open as a page

In typescript-eslint, why does the @typescript-eslint/no-floating-promises rule need type information, and how do you enable typed linting in a flat config?

level: middleimportance: must knowfreq 22%

basics

~20 s

Whether a call like saveRefill(order) returns a Promise depends on its declared type, often in another file, which only TypeScript's checker knows. Use recommendedTypeChecked and set parserOptions.projectService to true so the parser asks TypeScript for each file's types.

open as a page

With typescript-eslint, how does parserOptions.projectService find each file's type information differently from parserOptions.project, and why is it now the recommended option?

level: middleimportance: should knowfreq 12%

basics

~20 s

parserOptions.project uses tsconfig files you name, or each file's nearest one with true. projectService asks TypeScript's project service, the machinery editors use, for each file's nearest tsconfig.json: no paths to maintain, and lint types match the editor's.

open as a page

After a TypeScript repository switched to typescript-eslint's type-checked presets, its ESLint job went from 40 seconds to 6 minutes — why, and how do you find what to fix?

level: seniorimportance: should knowfreq 10%

basics

~20 s

Typed linting makes TypeScript build and analyse the whole project before typed rules can run, so lint time approaches type-check time. Time a plain tsc run as the baseline, profile rules with TIMING=1, then check wide tsconfig includes, default-project files and memory.

open as a page

With ESLint 10 and typescript-eslint's projectService, eslint.config.js and scripts/*.mjs fail with "was not found by the project service" — how do you fix each?

level: seniorimportance: nice to knowfreq 7%

basics

~20 s

No tsconfig.json includes those files, so the project service cannot type them. Add them to tsconfig.json's include, list a few in projectService.allowDefaultProject, or turn typed linting off for them with a files-scoped disableTypeChecked object; ignore files you never lint.

open as a page