TypeScript ESLint

Common errors

• ESLint was configured to run on <file-path> using 'parserOptions.project'. However, that TSConfig does not / none of those TSConfigs include this file.

  cause The linted file is not included in the TypeScript project(s) specified in `parserOptions.project` in your ESLint configuration, preventing type information from being generated.
  fix Add the file's path to the `include` array in your `tsconfig.json`. If the file should not be type-checked (e.g., a JavaScript file or a configuration file), use ESLint's `ignorePatterns` or an `overrides` block in your `.eslintrc.js` to exclude it from type-aware linting.

• Unexpected global require.

  cause The `no-require-imports` rule (often enabled in recommended configs) disallows `require()` invocations, promoting ES Module `import` syntax.
  fix Replace `require()` calls with ES Module `import` statements (e.g., `import * as Module from 'module';` or `import { Name } from 'module';`). If you need to import JSON files outside of your TS root or in environments that don't support JSON modules, configure the `allow` option of the `no-require-imports` rule.

• '<variable>' is not defined. (no-undef)

  cause The ESLint core `no-undef` rule does not use TypeScript's type information to determine global variables. This often leads to false positives in TypeScript projects, especially for globally declared types or namespaces.
  fix Disable the ESLint core `no-undef` rule and rely on TypeScript's built-in checks instead. TypeScript provides superior global variable checking. If you have global types from third-party `@types` packages, you might need to configure ESLint's `env` or `globals` settings.

• x is not assignable to type Y. Type 'A' is not assignable to type 'B'.

  cause This is a general TypeScript type error, not an ESLint specific error. It indicates a type mismatch detected by the TypeScript compiler itself, which ESLint then reports through its parser services if type-aware rules are enabled.
  fix This requires addressing the underlying TypeScript type incompatibility in your code. Consult TypeScript documentation on type safety, refactor your code to ensure correct type assignments, or use type assertions (`as Type`) or non-null assertions (`!`) judiciously if you are certain of the type. Reviewing relevant `typescript-eslint` rules like `no-explicit-any` or `no-unsafe-*` can help.

Warnings

• breaking Version 8 introduced breaking changes to its peer dependency requirements. ESLint must be `^8.57.0 || ^9.0.0 || ^10.0.0`, Node.js must be `^18.18.0 || ^20.9.0 || >=21.1.0`, and TypeScript must be `>=4.8.4 <6.1.0`.
  Fix: Ensure your `package.json` specifies compatible versions for `eslint`, `typescript`, and your Node.js runtime environment. Update these packages if necessary.
• breaking The `@typescript-eslint/ban-types` rule was removed and replaced with more targeted rules in v8, namely `@typescript-eslint/no-restricted-types`, `@typescript-eslint/no-empty-object-type`, `@typescript-eslint/no-unsafe-function-type`, and `@typescript-eslint/no-wrapper-object-types`. The `prefer-ts-expect-error` rule was also removed in favor of `ban-ts-comment`.
  Fix: Migrate your configuration by removing `ban-types` and `prefer-ts-expect-error` rules. Enable the new, specific rules from `@typescript-eslint` as needed to replicate previous functionality or achieve desired linting. Consider using the recommended configurations for v8.
• breaking The default configurations (`tseslint.configs.recommended`, `strict`, `all`) have been updated in v8, which may introduce new linting errors or changes in behavior. This is a common occurrence in major version upgrades.
  Fix: After upgrading, review your project's linting reports. It is often recommended to remove all existing custom rule configurations and then re-extend from the new recommended presets, addressing any new errors systematically.
• gotcha Using `parserOptions.project` for type-aware linting requires that all linted files are explicitly included in one of the specified `tsconfig.json` files. Files not included will lead to errors like 'ESLint was configured to run... However, that TSConfig does not / none of those TSConfigs include this file'.
  Fix: Ensure all files you intend to lint with type information are covered by the `include` or `files` array in your `tsconfig.json`. Alternatively, for files not meant for type-aware linting (e.g., config files, `.js` files), use ESLint's `ignorePatterns` or `overrides` to disable type-aware rules for those specific files.
• gotcha ESLint's built-in `--cache` option is generally not recommended for projects using `typescript-eslint`'s type-aware rules. The cache mechanism doesn't reliably account for cross-file type dependencies, leading to potentially stale or incorrect linting results.
  Fix: Avoid using the `--cache` flag when running ESLint with type-aware rules. For performance, ensure your linting setup is efficient and consider running ESLint as part of a pre-commit hook rather than relying on its built-in caching for type-aware checks.
• deprecated TypeScript 5.0 deprecated the `importsNotUsedAsValues` `tsconfig.json` option. While `typescript-eslint` still provides the `consistent-type-imports` rule, relying on the compiler option is no longer advised.
  Fix: Remove `importsNotUsedAsValues` from your `tsconfig.json`. Instead, use the `@typescript-eslint/consistent-type-imports` ESLint rule to enforce explicit `import type` where appropriate, improving clarity and preventing unintentional runtime imports.

Install

• npm install typescript-eslint npm
• yarn add typescript-eslint yarn
• pnpm add typescript-eslint pnpm

Imports

• tseslint
  wrong:

  const tseslint = require('typescript-eslint');

  correct:

  import tseslint from 'typescript-eslint';

  For ESLint's Flat Config, the unified `typescript-eslint` package provides the main entry point, including parser and plugin configs, typically imported as a default export. CommonJS `require()` is not supported for modern flat configs.
• defineConfig

  import { defineConfig } from 'eslint/config';

  This is an ESLint core utility (not from `typescript-eslint` itself) recommended for type-safe flat configurations. It provides IntelliSense for your `eslint.config.js` or `eslint.config.mjs`.
• js.configs.recommended

  import js from '@eslint/js';

  ESLint's own recommended rules are imported from `@eslint/js`, not `typescript-eslint`.

Quickstart

This quickstart demonstrates how to set up `typescript-eslint` with ESLint's flat configuration format, including recommended rules, type-aware linting, and custom rule overrides for both TypeScript and JavaScript files.

/* eslint.config.mjs */
// @ts-check

import js from '@eslint/js';
import tseslint from 'typescript-eslint';
import { defineConfig } from 'eslint/config';

export default defineConfig(
  js.configs.recommended,
  ...tseslint.configs.recommended,
  {
    files: ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx'],
    languageOptions: {
      parserOptions: {
        project: true,
        tsconfigRootDir: import.meta.dirname,
      },
    },
    rules: {
      // Example custom rule: enforce consistent usage of type imports
      '@typescript-eslint/consistent-type-imports': 'error',
      // Example: disable a base ESLint rule that has a TypeScript equivalent
      'no-unused-vars': 'off',
      '@typescript-eslint/no-unused-vars': [
        'warn',
        { 'argsIgnorePattern': '^_' }
      ]
    },
  }
);

/* Example tsconfig.json */
// {
//   "compilerOptions": {
//     "target": "ES2022",
//     "module": "ESNext",
//     "esModuleInterop": true,
//     "forceConsistentCasingInFileNames": true,
//     "strict": true,
//     "skipLibCheck": true,
//     "jsx": "react-jsx",
//     "lib": ["ES2022", "DOM", "DOM.Iterable"],
//     "include": ["src"]
//   }
// }