Announcing typescript-eslint v8 Beta
typescript-eslint is the tooling that enables standard JavaScript tools such as ESLint and Prettier to support TypeScript code. We've been working on a set of breaking changes and general features that we're excited to get in front of users soon. And now, we're excited to say that typescript-eslint v8 is ready for public beta testing! π
Our plan for typescript-eslint v8 is to:
- Have users try out betas starting in May of 2024
- Respond to user feedback for the next ~1-2 months
- Release a stable version within the next ~1-2 months
Nothing mentioned in this blog post is set in stone.
If you feel passionately about any of the choices we've made here β positively or negatively β then do let us know on the typescript-eslint Discord's #v8
channel!
Trying Out v8β
Please do try out the typescript-eslint v8 beta!
As A New Userβ
If you don't yet use typescript-eslint, you can go through our configuration steps on the v8 Getting Started docs. It'll walk you through setting up typescript-eslint in a project.
To use v8 specifically, see the following section for an updated install command.
As An Existing Userβ
If you already use typescript-eslint, you'll need to first replace your package's previous versions of @typescript-eslint/eslint-plugin
and @typescript-eslint/parser
with @rc-v8
versions:
- Flat Config
- Legacy Config
npm i typescript-eslint@rc-v8 --save-dev
npm i @typescript-eslint/eslint-plugin@rc-v8 @typescript-eslint/parser@rc-v8 --save-dev
We highly recommend then basing your ESLint configuration on the reworked typescript-eslint recommended configurations β especially if it's been a while since you've reworked your linter config.
User-Facing Changesβ
These are the changes that users of typescript-eslint βgenerally, any developer running ESLint on TypeScript codeβ should pay attention to when upgrading typescript-eslint from v7 to v8.
β³ indicates a change that has been scheduled for v8 but not yet released. We'll update this blog post as the corresponding pull requests land.
ESLint v9 Supportβ
typescript-eslint v8 ships with full support for ESLint v9.
typescript-eslint v7 was our first version that supported ESLint's new "flat" config file format, which was already available in ESLint v8. ESLint v9 still supports ESLint's older legacy config file format so our tooling does as well. However, ESLint v9 also includes a set of breaking changes that we added support for in typescript-eslint v8. See the ESLint v9 release blog post for more details.
Project Serviceβ
The biggest new feature added in this version is the stability of our new "project service".
In short, the project service is a new way to enable typed linting that is generally easier to configure and faster at runtime than our previous offerings.
It's been experimentally available since v6.1.0 under the name EXPERIMENTAL_useProjectService
; now, we've renamed it to projectService
.
You can use the new project service in your configuration instead of the previous parserOptions.project
:
import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';
export default tseslint.config(
eslint.configs.recommended,
...tseslint.configs.recommendedTypeChecked,
{
languageOptions: {
parserOptions: {
project: true,
projectService: true,
tsconfigRootDir: import.meta.dirname,
},
},
},
);
The project service will automatically find the closest tsconfig.json
for each file (like project: true
).
It also allows enabling typed linting for files not explicitly included in a tsconfig.json
.
This should remove the need for custom tsconfig.eslint.json
files to lint files like eslint.config.js
!
Typed linting for out-of-project files can be done by specifying two properties of a parserOptions.projectService
object:
allowDefaultProject
: a glob of a small number of out-of-project files to enable a slower default project ondefaultProject
: path to a TypeScript configuration file to use for the slower default project
import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';
export default tseslint.config(
eslint.configs.recommended,
...tseslint.configs.recommendedTypeChecked,
{
languageOptions: {
parserOptions: {
project: ['packages/*/tsconfig.json', 'tsconfig.eslint.json'],
projectService: {
allowDefaultProject: ['./*.js'],
defaultProject: './tsconfig.json',
},
tsconfigRootDir: import.meta.dirname,
},
},
},
);
Internally, the project service uses the same TypeScript APIs that editors such as VS Code use. Doing so should make it harder to accidentally configure different type information for ESLint than what you see in day-to-day editing.
We're thrilled to have the project service option promoted to stable in v8.
We'll soon release a dedicated parserOptions
blog post walking through the new option in more details.
π
Updated Configuration Rulesβ
Every new major version of typescript-eslint comes with changes to which rules are enabled in the preset configurations and with which options. Because this release also includes a reworking of the configurations themselves, the list of changes is too large to put in this blog post. Instead see the table in Changes to configurations for 8.0.0 for a full list of the changes.
Please do try out the new rule configurations presets and let us know in that discussion!
If your ESLint configuration contains many rules
configurations, we suggest the following strategy to start anew:
- Remove all your rules configurations
- Extend from the preset configs that make sense for you
- Run ESLint on your project
- In your ESLint configuration, turn off any rules creating errors that don't make sense for your project β with comments explaining why
- In your ESLint configuration and/or with inline
eslint-disable
comments, turn off/downgrade to "warn" any rules creating too many errors for you to fix β with "TODO" comments linking to tracking issues/tickets to re-enable them
Rule Breaking Changesβ
Several rules are changed in significant enough ways to be considered breaking changes:
- Rules: Deprecate prefer-ts-expect-error in favor of ban-ts-comment
- If you have
@typescript-eslint/prefer-ts-expect-error
manually enabled, remove that, and instead either use a recommended config or manually enable@typescript-eslint/ban-ts-comment
- If you have
- chore(eslint-plugin): deprecate no-var-requires in favor of no-require-imports
- If you have
@typescript-eslint/no-var-requires
manually enabled, remove that, and instead either use a recommended config or manually enable@typescript-eslint/no-require-imports
- If you have
- feat(eslint-plugin): remove deprecated no-throw-literal rule
- If you have
@typescript-eslint/no-throw-literal
manually enabled, remove that, and instead either use a recommended config or manually enable@typescript-eslint/only-throw-error
- If you have
- feat(eslint-plugin): [no-useless-template-literals] rename to no-useless-template-expression (deprecate no-useless-template-literals) and fix: no-useless-template-expression -> no-unnecessary-template-expression
- Find-and-replace text from
no-useless-template-literals
tono-unnecessary-template-expression
- Find-and-replace text from
- feat(eslint-plugin): deprecate no-loss-of-precision extension rule
- If you have
@typescript-eslint/no-loss-of-precision
manually enabled, replace it with the base ruleno-loss-of-precision
.
- If you have
- feat(eslint-plugin): remove formatting/layout rules
- If you're using any of the old deprecated formatting rules, see eslint.style for their new equivalents
- feat(eslint-plugin): [prefer-nullish-coalescing] change ignoreConditionalTests default to true
- If you want to have the rule check conditional tests, set its
ignoreConditionalTests
option tofalse
in your ESLint config
- If you want to have the rule check conditional tests, set its
- feat(eslint-plugin): [no-unused-vars] align catch behavior to ESLint 9
- If you want
@typescript-eslint/no-unused-vars
to ignore caught errors, enable itscaughtErrors
option to'none'
in your ESLint config
- If you want
Replacement of ban-types
β
@typescript-eslint/ban-types
has long been one of the more controversial rules in typescript-eslint.
It served two purposes:
- Allowing users to ban a configurable list of types from being used in type annotations
- Banning confusing or dangerous built-in types such as
Function
andNumber
Notably, ban-types
banned the built-in {}
("empty object") type in TypeScript.
The {}
type is a common source of confusion for TypeScript developers because it matches any non-nullable value, including primitives like ""
.
Banning {}
in ban-types
was helpful to prevent developers from accidentally using it instead of a more safe type such as object
.
On the other hand, there are legitimate uses for {}
, and banning it by default was harmful in those cases.
typescript-eslint v8 deletes the ban-types
rule and replaces it with several more targeted rules:
@typescript-eslint/no-restricted-types
is the new rule for banning a configurable list of type names. It has no options enabled by default.@typescript-eslint/no-empty-object-type
bans the built-in{}
type in confusing locations.@typescript-eslint/no-unsafe-function-type
bans the built-inFunction
type@typescript-eslint/no-wrapper-object-types
bansObject
and built-in class wrappers such asNumber
.
To migrate to the new rules:
- If you were disabling the ban on
{}
, consider enabling@typescript-eslint/no-empty-object-type
, as it allows some cases of{}
that were previously banned. - If you were banning any configurable types lists, provide a similar configuration to
no-restricted-types
. - If you have
@typescript-eslint/ban-types
manually enabled, it will no longer ban:{}
orobject
: use a recommended config or manually enable@typescript-eslint/no-empty-object-type
Function
: use a recommended config or manually enable@typescript-eslint/no-unsafe-function-type
Number
or other built-in uppercase types: use a recommended config or manually enable@typescript-eslint/no-wrapper-object-types
- If you have
@typescript-eslint/no-empty-interface
manually enabled, remove that, and instead either use a recommended config or manually enable@typescript-eslint/no-empty-object-type
For more details, see the issues and pull requests that split apart the ban-types
rule:
- Enhancement: [ban-types] Split the ban into a separate, better-phrased rule
- feat(eslint-plugin): split no-empty-object-type out from ban-types and no-empty-interface
- Enhancement: [ban-types] Split into default-less no-restricted-types and more targeted type ban rule(s)
- feat(eslint-plugin): replace ban-types with no-restricted-types, no-unsafe-function-type, no-wrapper-object-types
Tooling Breaking Changesβ
- β³ Enhancement: Error if configuration options aren't provided as expected
- This should only cause errors if you had an invalid config.
- fix(typescript-estree): enable dot globs for project by default
- This will cause any
parserOptions.project
globs to match dot (.
) directories. If you don't want to match them then use a more specific set of globs, or switch toparserOptions.projectService
.
- This will cause any
- feat(typescript-estree): remove slow deprecated and isolated programs
- If you were still using
parserOptions.DEPRECATED__createDefaultProgram
, switch toparserOptions.projectService
(recommended) orparserOptions.project
.
- If you were still using
- feat(typescript-estree): rename automaticSingleRunInference to disallowAutomaticSingleRunInference
- We've updated the default to be an opt-out - meaning you no longer need to enable it:
parserOptions: {
automaticSingleRunInference: true,
// ...
}
- We've updated the default to be an opt-out - meaning you no longer need to enable it:
- chore: bump minimum versions for v8
- ESLint support range was changed from
^8.56.0
to^8.57.0
- Node.js support range was changed from
^18.18.0 || >=20.0.0
to^18.18.0 || ^20.9.0 || >=21.1.0
- TypeScript support range was changed from
>=4.7.4 <5.5.0
to>=4.8.4 <5.5.0
- ESLint support range was changed from
- Parser: remove EXPERIMENTAL_useSourceOfProjectReferenceRedirect in favor of project service
- We now recommend using the new
parserOptions.projectService
instead
- We now recommend using the new
Developer-Facing Changesβ
typescript-eslint v8 comes with a suite of cleanups and improvements for developers using its Node.js APIs as well. If you author any ESLint plugins or other tools that interact with TypeScript syntax, then we recommend you try out typescript-eslint v8 soon. It includes some breaking changes that you may need to accommodate for.
If you're having trouble working with the changes, please let us know on the typescript-eslint Discord's #v8
channel!
AST Breaking Changesβ
These changes are to the AST shapes generated by typescript-eslint when parsing code. If you author any ESLint rules that refer to the syntax mentioned by them, these are relevant to you.
- β³ Enhancement: add strict parent types for nodes that have well-defined parents
- This will help you remove some unnecessary conditions - we suggest using
@typescript-eslint/no-unnecessary-condition
to help find the unnecessary checks!
- This will help you remove some unnecessary conditions - we suggest using
- feat(typescript-estree): split TSMappedType typeParameter into constraint and key
- If your code handles mapped types, change from
node.typeParameter.constraint
tonode.constraint
and fromnode.typeParameter.name
tonode.key
- If your code handles mapped types, change from
- feat(ast-spec): remove deprecated type params
- If you haven't already you must stop using those removed AST properties that were already marked as
@deprecated
- If you haven't already you must stop using those removed AST properties that were already marked as
- fix(typescript-estree): add TSEnumBody node for TSEnumDeclaration body #8920
- If your code handles enums, switch from
node.members
tonode.body.members
- If your code handles enums, switch from
Custom Rule meta.docs
Typesβ
@typescript-eslint/utils
has long exported a RuleCreator
utility for making custom well-typed custom ESLint rules.
That RuleCreator
is used internally by @typescript-eslint/eslint-plugin
β and in fact, up through typescript-eslint v7, it hardcoded the same types for rules' meta.docs
as @typescript-eslint/eslint-plugin
!
In typescript-eslint v8, we've made two changes to RuleCreator
:
- Rule
meta.docs
by default only allows the properties defined in ESLint's Custom Rules > Rule Structure docs:description
andurl
RuleCreator
allows an optional type parameter to specify additional allowed properties
For example, this rule includes the common meta.docs.recommended
property as a boolean
:
interface MyPluginDocs {
recommended: boolean;
}
const createRule = ESLintUtils.RuleCreator<MyPluginDocs>(
name => `https://example.com/rule/${name}`,
);
createRule({
// ...
meta: {
docs: {
description: '...',
recommended: true,
},
// ...
},
});
See feat(utils): allow specifying additional rule meta.docs in RuleCreator for more details.
Support for multi-pass fixes in RuleTester
β
The RuleTester
provided by @typescript-eslint/rule-tester
is a fork of ESLint's RuleTester
.
One limitation of the original RuleTester
is that it is not possible to verify the individual applied fixes when a rule provides multiple rounds of fixes.
The original RuleTester
applies only the first fix when there is conflict between two fixes.
In typescript-eslint v8, RuleTester
tries to apply all possible fixes for each test case.
If your rule tests had some test cases that required multi-pass fixes, you will see some test failures.
To fix these failures, provide an array of strings for output
which specifies the output after each fix pass.
import { RuleTester } from '@typescript-eslint/rule-tester';
import rule from '../src/rules/my-rule.ts';
const ruleTester = new RuleTester();
ruleTester.run('my-rule', rule, {
valid: [
/* ... */
],
invalid: [
{
code: 'const a = 1;',
// Remove the line with string form of `output`
output: 'const b = 1;',
// Add the line with array form of `output`
output: ['const b = 1;', 'const c = 1;'],
errors: [
/* ... */
],
},
],
});
See [rule-tester] support multipass fixes for more details.
Other Developer-Facing Breaking Changesβ
- β³ Repo: Rule [options] parameter should be non-nullable if defaultOptions exists
- feat(parser): always enable comment, loc, range, tokens
- If you were manually calling
@typescript-eslint/parser
functions, those options are no longer necessary to provide
- If you were manually calling
- chore(type-utils)!: remove IsNullableTypeOptions interface
- If you were using
isNullableType
, you can omit its section parameter
- If you were using
- feat(utils): swap LegacyESLint out for FlatESLint as ESLint export
- If you still need to use the class corresponding to legacy ("eslintrc") configs, switch from importing
ESLint
toLegacyESLint
- If you still need to use the class corresponding to legacy ("eslintrc") configs, switch from importing
- chore(type-utils): remove getTypeArguments
- If you were using
getTypeArguments
, call a TypeScript type checker'schecker.getTypeArguments
instead
- If you were using
- feat(utils): remove deprecated context helpers
- You should consider dropping support for older ESLint versions and migrate to the new APIs.
Appreciationβ
We'd like to extend a sincere thank you to everybody who pitched in to make typescript-eslint v8 possible.
- Ourselves on the maintenance team:
- Community contributors whose PRs were merged into the 8.0.0 release:
- Abraham Guo
- Collin Bachman
- Thomas HuchedΓ©
- Yukihiro Hasegawa
- (more to come as PRs are merged!)
See the v8.0.0 milestone for the list of issues and associated merged pull requests.
Supporting typescript-eslintβ
If you enjoyed this blog post and/or use typescript-eslint, please consider supporting us on Open Collective. We're a small volunteer team and could use your support to make the ESLint experience on TypeScript great. Thanks! π