Typed Linting

Editor ESLint reports become out-of-date after file changes

There is a known issue in at least VS Code with typed linting that files might have out-of-date lint errors after multiple updates to files on disk. The root cause is that ESLint doesn't provide a way for editors to know about cross-file dependencies, such as type information. This results in files receiving out-of-date type information when files they import from are changed.

You might see this as erroneous no-unsafe-* rule complaints on any or error typed values. Other rules may be more subtly incorrect.

For now, the workaround is to run the Restart ESLint Server command in VS Code (or an equivalent in other editors) when types get out of date.

See ESLint does not re-compute cross-file information on file changes (microsoft/vscode-eslint#1774) for more information.

How do I disable type-checked linting for a file?

Use ESLint's configuration objects with our disable-type-checked config to disable type checking for a files match that includes that file.

For example, to disable type-checked linting on all .js files:

Flat Config

eslint.config.mjs

import tseslint from 'typescript-eslint';

export default tseslint.config(
  // ... the rest of your config ...
  {
    files: ['**/*.js'],
    extends: [tseslint.configs.disableTypeChecked],
  },
);

Legacy Config

.eslintrc.cjs

module.exports = {
  // ... the rest of your config ...
  overrides: [
    {
      extends: ['plugin:@typescript-eslint/disable-type-checked'],
      files: ['./**/*.js'],
    },
  ],
};

Alternatively to disable type checking for files manually, you can set parserOptions: { project: false } to an override for the files you wish to exclude.

typescript-eslint thinks my variable is never nullish / is any / etc., but that is clearly not the case to me

Our type-aware rules almost always trust the type information provided by the TypeScript compiler. Therefore, an easy way to check if our rule is behaving correctly is to inspect the type of the variable in question, such as by hovering over it in your IDE.

If the IDE also shows that the type is never nullish / is any, you need to fix the type. A very common case is with the no-unnecessary-condition rule. Take this code for example:

let condition = false;

const f = () => (condition = true);
f();

if (condition) {
  //^^^^^^^^^ Unnecessary conditional, value is always falsy.
}

You can see that the type of condition is actually the literal type false by hovering over it in your IDE. In this case, typescript-eslint cannot possible know better than TypeScript itself, so you need to fix the report by fixing the type, such as through an assertion (let condition = false as boolean).

If the IDE provides different type information from typescript-eslint's report, then make sure that the TypeScript setup used for your IDE, typescript-eslint, and tsc are the same: the same TypeScript version, the same type-checking compiler options, and the same files being included in the project. For example, if a type is declared in another file but that file is not included, the type will become any, and cause our no-unsafe-* rules to report.

Are TypeScript project references supported?

Yes, but only with EXPERIMENTAL_useProjectService.

See issue #2094 discussing project references for more details.

Project Service Issues

I get errors telling me "Having many files run with the default project is known to cause performance issues and slow down linting."

These errors are caused by attempting to use the projectService to lint a file not explicitly included in a tsconfig.json.

For each file being reported:

• If you do not want to lint the file:
  • Use one of the options ESLint offers to ignore files, such an ignores config key.
• If you do want to lint the file:
  • If you do not want to lint the file with type-aware linting: disable type-checked linting for that file.
  • If you do want to lint the file with type-aware linting:
    1. If possible, add the file to the closest tsconfig.json's include. For example, allowing .js files:
       tsconfig.json

       "include": [
         "src",
       + "*.js"
       ]
    2. Otherwise, consider setting parserOptions.createProjectService.allowDefaultProject.

typescript-eslint allows up to 8 "out of project" files by default. Each file causes a new TypeScript "program" to be built for each file it includes, which incurs a performance overhead for each file.

If you cannot do this, please file an issue on typescript-eslint's typescript-estree package telling us your use case and why you need more out-of-project files linted. Be sure to include a minimal reproduction we can work with to understand your use case!

Traditional Project Issues

I get errors telling me "ESLint was configured to run ... However, that TSConfig does not / none of those TSConfigs include this file"

These errors are caused by an ESLint config requesting type information be generated for a file that isn't included in the TypeScript configuration.

Fixing the Error

• If you do not want to lint the file:
  • Use one of the options ESLint offers to ignore files, namely a .eslintignore file, or ignorePatterns config.
• If you do want to lint the file:
  • If you do not want to lint the file with type-aware linting:
    • Use ESLint's configuration objects with our disable-type-checked config to disable type checking for just that type of file.
  • If you do want to lint the file with type-aware linting:
    • Check the include option of each of the TSConfigs that you provide to parserOptions.project - you must ensure that all files match an include glob, or else our tooling will not be able to find it.
      • If the file is a .cjs, .js, or .mjs file, make sure allowJs is enabled.
    • If your file shouldn't be a part of one of your existing tsconfigs (for example, it is a script/tool local to the repo), then consider creating a new tsconfig (we advise calling it tsconfig.eslint.json) in your project root which lists this file in its include. For an example of this, you can check out the configuration we use in this repo:
      • tsconfig.eslint.json
      • eslint.config.mjs

More Details

This error may appear from the combination of two things:

• The ESLint configuration for the source file specifies at least one TSConfig file in parserOptions.project
• None of those TSConfig files includes the source file being linted
  • Note that files with the same name and different extension may not be recognized by TypeScript: see parserOptions.project docs

When TSConfig files are specified for parsing a source file, @typescript-eslint/parser will use the first TSConfig that is able to include that source file (per aka.ms/tsconfig#include) to generate type information. However, if no specified TSConfig includes the source file, the parser won't be able to generate type information.

This error most commonly happens on config files or similar that are not included in their project TSConfig(s). For example, many projects have files like:

• An .eslintrc.cjs / eslint.config.mjs with parserOptions.project: true
• A tsconfig.json with include: ["src"]

In that case, viewing the file in an IDE with the ESLint extension will show the error notice that the file couldn't be linted because it isn't included in tsconfig.json.

See our docs on type aware linting for more information.

I get errors telling me "The file must be included in at least one of the projects provided"

You're using an outdated version of @typescript-eslint/parser. Update to the latest version to see a more informative version of this error message, explained above.