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 |
configs | Our eslint (flat) configs |
parser | Our parser |
plugin | Our plugin |
Installation
- npm
- Yarn
- pnpm
npm i typescript-eslint
yarn add typescript-eslint
pnpm add typescript-eslint
Migrating from "legacy" config setups
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, see ESLint's Configuration Migration Guide.
Usage
The simplest usage of this package would be:
// @ts-check
import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';
export default tseslint.config(
eslint.configs.recommended,
...tseslint.configs.recommended,
);
This config file exports a flat config that enables both the core eslint recommended config and our recommended config.
For more information on the tseslint.config
function see config(...)
below.
Advanced usage
Manually configuring our plugin and parser
You can declare our plugin and parser in your config via this package, for example:
// @ts-check
import eslint from '@eslint/js';
import jestPlugin from 'eslint-plugin-jest';
import tseslint from 'typescript-eslint';
export default tseslint.config({
plugins: {
'@typescript-eslint': tseslint.plugin,
},
languageOptions: {
parser: tseslint.parser,
parserOptions: {
projectService: true,
tsconfigRootDir: import.meta.dirname,
},
},
rules: {
'@typescript-eslint/no-unsafe-argument': 'error',
'@typescript-eslint/no-unsafe-assignment': 'error',
'@typescript-eslint/no-unsafe-call': 'error',
'@typescript-eslint/no-unsafe-member-access': 'error',
'@typescript-eslint/no-unsafe-return': 'error',
},
});
We strongly 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 currently flat 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
/dist
folders 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-jest
rules on test files only
// @ts-check
import eslint from '@eslint/js';
import jestPlugin from 'eslint-plugin-jest';
import tseslint from 'typescript-eslint';
export default 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-unsafe-argument': 'error',
'@typescript-eslint/no-unsafe-assignment': 'error',
'@typescript-eslint/no-unsafe-call': 'error',
'@typescript-eslint/no-unsafe-member-access': 'error',
'@typescript-eslint/no-unsafe-return': 'error',
},
},
{
// disable type-aware linting on JS files
files: ['**/*.js'],
...tseslint.configs.disableTypeChecked,
},
{
// enable jest rules on test files
files: ['test/**'],
...jestPlugin.configs['flat/recommended'],
},
);
config(...)
The config
function is a variadic identity function which is a fancy way of saying that it's a function with a spread argument that accepts any number flat config objects and returns the objects unchanged. It exists as a way to quickly and easily provide types for your flat config file without the need for JSDoc type comments.
By using this function you will get autocomplete and documentation for all config properties in addition to TypeScript errors, should you provide invalid values.
- With helper
- Without helper
// @ts-check
import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';
export default tseslint.config(
eslint.configs.recommended,
...tseslint.configs.recommended,
{
/*... */
},
// ...
);
// @ts-check
import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';
/** @type {import('@typescript-eslint/utils').TSESLint.FlatConfig.ConfigFile} */
export default [
eslint.configs.recommended,
...tseslint.configs.recommended,
{
/*... */
},
// ...
];
We strongly 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 but otherwise it will not impact your ability to use our tooling.
Flat config extends
The tseslint.config
utility function also adds handling for the extends
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:
export default tseslint.config({
files: ['**/*.ts'],
extends: [
eslint.configs.recommended,
...tseslint.configs.recommended,
],
rules: {
'@typescript-eslint/array-type': 'error',
'@typescript-eslint/consistent-type-imports': 'error',
},
});
// is the same as writing
export default [
...[
eslint.configs.recommended,
...tseslint.configs.recommended,
].map(conf => ({
...conf,
files: ['**/*.ts'],
})),
{
files: ['**/*.ts'],
rules: {
'@typescript-eslint/array-type': 'error',
'@typescript-eslint/consistent-type-imports': 'error',
},
},
];
We found that this is a pretty 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 this is a very common way to disable TS-specific linting setups on JS files:
export default 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',
},
});