skip to content

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%

answer

  1. who picks the tsconfig
  2. paths you list against nearest tsconfig.json
  3. the same service editors use
  4. no tsconfig.eslint.json needed
  5. both set throws an error

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.

solid answer

~40 s

`parserOptions.project` takes a path, glob or array of tsconfig files, or `true` for each file's nearest `tsconfig.json`; every linted file must be included by one of them, which is why many repositories grew a `tsconfig.eslint.json`, and referenced projects are not followed unless you list them. `parserOptions.projectService` (default `false`) asks TypeScript's **project service**, the same machinery editors use, for each file's nearest `tsconfig.json`, so most repositories need no paths, monorepos need no extra setup, and lint sees the same types as the editor. typescript-eslint 8 recommends it for easier configuration and faster linting. Set one, not both: with both, the parser throws `Enabling "project" does nothing when "projectService" is enabled.` Relative paths in either option resolve from `tsconfigRootDir`, which defaults to the ESLint config file's directory.

go deeper

for a junior

Know that typed rules need a tsconfig, and that typescript-eslint's recommended way to supply one is parserOptions.projectService: true.

for a middle

Contrast the two options: listed tsconfig paths and an inclusion requirement against TypeScript's project service picking each file's nearest tsconfig.json. Name the error that fires when both are set.

for a senior

Plan the migration off project: retire tsconfig.eslint.json, fold its files into tsconfig.json, handle stray files, and pin tsconfigRootDir when ESLint runs from other directories.

for a principal

Argue for one source of type truth: lint, editor and build reading the same tsconfig.json removes a class of disagreements, at the cost of fewer escape hatches for odd files.

## Why the parser needs a tsconfig at all Typed rules ask TypeScript's type checker about nodes, and the checker works on a **program**: a set of files plus the compiler options that govern them. Before typescript-eslint can answer a typed rule for `src/refill/submit.ts`, it has to know which `tsconfig.json` that file belongs to. The two parser options answer that question in different ways. ## `parserOptions.project`: you name the tsconfigs `project` accepts several forms: - `true`: use the `tsconfig.json` nearest to each source file. - A path such as `'./tsconfig.json'`, a glob such as `'./packages/*/tsconfig.json'`, or an array of both. - `false` or `null`: switch type-aware parsing off, for example in an object that targets a subset of files. Its rules follow from "you name them": - Every linted file must be **included** by one of the named tsconfigs, or the parser reports that the file is not in any of them. Teams often add a `tsconfig.eslint.json` whose `include` covers tests, scripts and config files. - For each file, the **first** listed tsconfig that includes it supplies its types. - Wide globs with `**` cost a lot of disk access; typescript-eslint advises a single `*` per segment. - Project references are **not followed** automatically: each referenced tsconfig has to be listed. ## `parserOptions.projectService`: TypeScript finds them `projectService` defaults to `false` and takes `true` or an options object. It hands the lookup to TypeScript's **project service**, the API editors use to decide which project an open file belongs to: - Each file gets the `tsconfig.json` (or `jsconfig.json`) **nearest** to it. Other names such as `tsconfig.eslint.json` are never read. - Monorepos with one tsconfig per package need **no extra configuration**, and project references work. - Lint sees the **same type information as the editor**, so a rule's report matches what hovering in the editor shows. - Files no tsconfig includes can be allowed in small numbers through `projectService.allowDefaultProject`; everything else must be included or kept away from typed rules. typescript-eslint 8 states the recommendation plainly: use `projectService` instead of `project` for easier configuration and faster linting, and keep `project` as the alternative for cases that need finer control. ## Side by side | | `project` | `projectService` | |---|---|---| | How the tsconfig is chosen | Paths or globs you list, or nearest with `true` | Nearest `tsconfig.json` via TypeScript's project service | | A custom name like `tsconfig.eslint.json` | Usable, by path | Not read | | Project references | Not followed; list each one | Supported | | Files no tsconfig includes | Error naming the tsconfigs that miss the file | Parsing error unless listed in `allowDefaultProject` | | Status in typescript-eslint 8 | Older alternative | Recommended | ## Setting both The two options are alternatives, not layers. If both are set, typescript-eslint throws: > `Enabling "project" does nothing when "projectService" is enabled. You can remove the "project" setting.` Remove `project`. An environment variable, `TYPESCRIPT_ESLINT_IGNORE_PROJECT_AND_PROJECT_SERVICE_ERROR=true`, suppresses the check, but `project` still does nothing while `projectService` is on. ## `tsconfigRootDir` `tsconfigRootDir` is the root that relative tsconfig paths in `project` and `projectService` (including `allowDefaultProject` globs) resolve from. It **defaults to the directory of the ESLint config file**, which typescript-eslint detects from the call stack. Unusual paths can fool that detection; pinning it removes the guesswork: ```js parserOptions: { projectService: true, tsconfigRootDir: import.meta.dirname, } ``` ## JavaScript files and either option A tsconfig leaves `.js`, `.cjs` and `.mjs` files out unless `allowJs` (or `checkJs`) is on, so typing JavaScript through either option means the nearest tsconfig must take them in. `projectService` adds one route `project` lacks: a file listed in `allowDefaultProject` can be typed even though no tsconfig includes it, without enabling `allowJs` anywhere. That route is meant for a few stray files such as the ESLint config itself; each such file has its own per-file cost. ## Moving from `project` to `projectService` 1. Replace `project: './tsconfig.eslint.json'` with `projectService: true`, and delete the `project` key. 2. Move whatever only `tsconfig.eslint.json` included into the `include` of the nearest `tsconfig.json`. typescript-eslint suggests keeping `tsconfig.json` for linting and the editor, and a separate file such as `tsconfig.build.json` for building. 3. Run the linter and resolve each file reported as not found by the project service: include it, list it in `allowDefaultProject` if it is one of a few stray files, or turn typed linting off for it.

  • Why might a team keep parserOptions.project after all?
    When it needs control `projectService` does not give: a tsconfig other than `tsconfig.json` for linting, or more out-of-project files than `allowDefaultProject` handles well. typescript-eslint names `project` as the fallback for those cases. The price is maintaining tsconfig paths and lint types that may differ from what the editor shows.
  • Typed linting works from the repository root but cannot find the tsconfig when ESLint runs from a subdirectory. What do you check?
    `tsconfigRootDir`. Relative tsconfig paths and `allowDefaultProject` globs resolve from it, and its default is detected from the call stack as the ESLint config file's directory. Setting `tsconfigRootDir: import.meta.dirname` in the config pins it, whatever directory ESLint starts in.

  • projectService reads tsconfig.eslint.json whenever one sits beside tsconfig.json.
  • Setting both project and projectService lets each cover different files.
  • projectService needs every package's tsconfig path listed in a monorepo.
  • project: true follows project references automatically, just like projectService.
  • projectService is just the new name for project, with identical behaviour.