Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
tseslint
✓ import tseslint from 'typescript-eslint';
✗ const tseslint = require('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`.
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"]
// }
// }
Debug
Known issues
breakingVersion 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`.fixEnsure your `package.json` specifies compatible versions for `eslint`, `typescript`, and your Node.js runtime environment. Update these packages if necessary.
affects: >=8.0.0
breakingThe `@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`.fixMigrate 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.
affects: >=8.0.0
breakingThe 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.fixAfter 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.
affects: >=8.0.0
gotchaUsing `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'.fixEnsure 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.
affects: >=5.0.0
gotchaESLint'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.fixAvoid 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.
affects: >=4.0.0
deprecatedTypeScript 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.fixRemove `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.
affects: >=7.0.0, TypeScript >=5.0
Errors
Common errors & fixes
ESLint was configured to run on <file-path> using 'parserOptions.project'. However, that TSConfig does not / none of those TSConfigs include this file.
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.
fixAdd 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.
The `no-require-imports` rule (often enabled in recommended configs) disallows `require()` invocations, promoting ES Module `import` syntax.
fixReplace `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)
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.
fixDisable 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'.
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.
fixThis 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.
Audit
Dependencies
eslintrequiredCore ESLint engine is required to run linting. typescript-eslint integrates with it.
typescriptrequiredRequired for parsing TypeScript code and providing type information to the linting rules.