typescript-eslint
Tooling which enables you to use TypeScript with ESLint
This package is the main entrypoint that you can use to consume our tooling with ESLint.
This package exports the following:
| Name | Description |
|---|---|
config | A utility function for creating type-safe flat configs -- seeconfig(...) |
configs | Shared ESLint (flat) configs |
parser | A re-export of@typescript-eslint/parser |
plugin | A re-export of@typescript-eslint/eslint-plugin |
Installation
- npm
- Yarn
- pnpm
npm i typescript-eslint
yarnadd typescript-eslint
pnpmadd typescript-eslint
Usage
We recommend getting started by usingtseslint.config helper function in your ESLint config:
// @ts-check
importeslintfrom'@eslint/js';
importtseslintfrom'typescript-eslint';
exportdefault tseslint.config(
eslint.configs.recommended,
tseslint.configs.recommended,
);
This config file exports a flat config that enables both thecore ESLint recommended config andour recommended config.
config(...)
tseslint.config(...) takes in any number of ESLint config objects, each of which may additionally include anextends array of configs to extend.tseslint.config(...) returns the equivalent ESLint config of applying the rest of the settings for each extension.
By using this function you will get autocomplete and documentation for all config properties.Additionally, if you provide invalid values, it can trigger informative TypeScript type errors.
- With helper
- Without helper
// @ts-check
import eslintfrom'@eslint/js';
import tseslintfrom'typescript-eslint';
exportdefault tseslint.config(
eslint.configs.recommended,
tseslint.configs.recommended,
{
/*... */
},
// ...
);
// @ts-check
import eslintfrom'@eslint/js';
import tseslintfrom'typescript-eslint';
/**@type{import('@typescript-eslint/utils').TSESLint.FlatConfig.ConfigFile} */
exportdefault[
eslint.configs.recommended,
...tseslint.configs.recommended,
{
/*... */
},
// ...
];
Westrongly recommend using this utility to improve the config authoring experience — however it is entirely optional.By choosing not to use it you lose editor autocomplete and type checking for config files.Otherwise itwill not impact your ability to use our tooling.
Flat configextends
Thetseslint.config utility function also adds handling for theextends property on flat config objects.This allows you to more easily extend shared configs for specific file patterns whilst also overriding rules/options provided by those configs:
exportdefault tseslint.config({
files:['**/*.ts'],
extends:[
eslint.configs.recommended,
tseslint.configs.recommended,
],
rules:{
'@typescript-eslint/array-type':'error',
// ...
},
});
// is the same as writing
exportdefault[
...[
eslint.configs.recommended,
...tseslint.configs.recommended,
].map(conf=>({
...conf,
files:['**/*.ts'],
})),
{
files:['**/*.ts'],
rules:{
'@typescript-eslint/array-type':'error',
// ...
},
},
];
We found that this is a common operation when writing ESLint configs which is why we provided this convenience property.
For example, in codebases with type-aware linting, a config object like the following is a common way to disable TypeScript-specific linting setups on JavaScript files:
exportdefault tseslint.config({
files:['**/*.js'],
extends:[tseslint.configs.disableTypeChecked],
rules:{
// turn off other type-aware rules
'other-plugin/typed-rule':'off',
// turn off rules that don't apply to JS code
'@typescript-eslint/explicit-function-return-type':'off',
},
});
Manual usage
typescript-eslint's recommended and stylistic configurations specify typescript-eslintparser andplugin options for you, so there is no need to manually provide those.However, in complex ESLint configurations, you may find yourself manually specifying those options yourself.
Manually configuring our plugin and parser
You can declare our plugin and parser in your config via this package, for example:
// @ts-check
importeslintfrom'@eslint/js';
importjestPluginfrom'eslint-plugin-jest';
importtseslintfrom'typescript-eslint';
exportdefault tseslint.config({
plugins:{
'@typescript-eslint': tseslint.plugin,
},
languageOptions:{
parser: tseslint.parser,
parserOptions:{
projectService:true,
tsconfigRootDir:import.meta.dirname,
},
},
rules:{
'@typescript-eslint/no-floating-promises':'error',
// ...
},
});
Westrongly recommend declaring our plugin with the namespace@typescript-eslint as shown above.If you use our shared configs this is the namespace that they use.This has been the standard namespace for our plugin for many years and is what users are most familiar with.
You may choose a different namespace - but note that currentlyflat configs allow the same plugin to be registered, configured, and have duplicate reports under multiple namespaces.
Usage with other plugins
Below is a more complex example of how you might use our tooling with flat configs.This config:
- Ignores
build/distfolders from being linted - Enables our plugin, our parser, and type-aware linting with a few of our popular type-aware rules
- Disables type-aware linting on JS files
- Enables the recommended
eslint-plugin-jestrules on test files only
// @ts-check
importeslintfrom'@eslint/js';
importjestPluginfrom'eslint-plugin-jest';
importtseslintfrom'typescript-eslint';
exportdefault tseslint.config(
{
// config with just ignores is the replacement for `.eslintignore`
ignores:['**/build/**','**/dist/**','src/some/file/to/ignore.ts'],
},
eslint.configs.recommended,
{
plugins:{
'@typescript-eslint': tseslint.plugin,
jest: jestPlugin,
},
languageOptions:{
parser: tseslint.parser,
parserOptions:{
projectService:true,
},
},
rules:{
'@typescript-eslint/no-floating-promises':'error',
// ...
},
},
{
// disable type-aware linting on JS files
files:['**/*.js'],
extends:[tseslint.configs.disableTypeChecked],
},
{
// enable jest rules on test files
files:['test/**'],
extends:[jestPlugin.configs['flat/recommended']],
},
);
Migrating from legacy.eslintrc configs
If you're migrating from a legacy.eslintrc configuration setup you likely have our plugin and parser installed separately.This package includes these as dependencies so you can freely uninstall your local references:
- npm
- Yarn
- pnpm
npm un @typescript-eslint/parser @typescript-eslint/eslint-plugin
yarn remove @typescript-eslint/parser @typescript-eslint/eslint-plugin
pnpm remove @typescript-eslint/parser @typescript-eslint/eslint-plugin
For more information on migrating from a "legacy" config setup, seeESLint's Configuration Migration Guide.