title | eleventyNavigation | ||||||||
---|---|---|---|---|---|---|---|---|---|
Migrate to v9.x |
|
ESLint v9.0.0 is a major release of ESLint, and as such, has several breaking changes that you need to be aware of. This guide is intended to walk you through the breaking changes.
The lists below are ordered roughly by the number of users each change is expected to affect, where the first items are expected to affect the most users.
- Node.js < v18.18, v19 are no longer supported
- Removed multiple formatters
- Removed
require-jsdoc
andvalid-jsdoc
rules eslint:recommended
has been updated
- Node.js < v18.18, v19 are no longer supported
- Removed multiple
context
methods - Removed
sourceCode.getComments()
- Function-style rules are no longer supported
meta.schema
is required for rules with optionsFlatRuleTester
is nowRuleTester
- Stricter
RuleTester
checks
ESLint is officially dropping support for these versions of Node.js starting with ESLint v9.0.0. ESLint now supports the following versions of Node.js:
- Node.js v18.18.0 and above
- Node.js v20.9.0 and above
- Node.js v21 and above
To address: Make sure you upgrade to at least Node.js v18.18.0 when using ESLint v9.0.0. One important thing to double check is the Node.js version supported by your editor when using ESLint via editor integrations. If you are unable to upgrade, we recommend continuing to use ESLint v8.56.0 until you are able to upgrade Node.js.
Related issue(s): #17595
ESLint v9.0.0 has removed the following formatters from the core:
Removed Formatter | Replacement npm Package |
---|---|
checkstyle |
eslint-formatter-checkstyle |
compact |
eslint-formatter-compact |
jslint-xml |
eslint-formatter-jslint-xml |
junit |
eslint-formatter-junit |
tap |
eslint-formatter-tap |
unix |
eslint-formatter-unix |
visualstudio |
eslint-formatter-visualstudio |
To address: If you are using any of these formatters via the -f
command line flag, you'll need to install the respective package for the formatter.
Related issue(s): #17524
The require-jsdoc
and valid-jsdoc
rules have been removed in ESLint v9.0.0. These rules were initially deprecated in 2018.
To address: Use the replacement rules in eslint-plugin-jsdoc
.
Related issue(s): #15820
Four new rules have been enabled in eslint:recommended
:
no-constant-binary-expression
no-empty-static-block
no-new-native-nonconstructor
no-unused-private-class-members
Additionally, the following rules have been removed from eslint:recommended
:
To address: Fix errors or disable these rules.
Related issue(s): #15576, #17446, #17596
ESLint v9.0.0 removes multiple deprecated methods from the context
object and moves them onto the SourceCode
object:
Removed on context |
Replacement(s) on SourceCode |
---|---|
context.getSource() |
sourceCode.getText() |
context.getSourceLines() |
sourceCode.getLines() |
context.getAllComments() |
sourceCode.getAllComments() |
context.getNodeByRangeIndex() |
sourceCode.getNodeByRangeIndex() |
context.getComments() |
sourceCode.getCommentsBefore() , sourceCode.getCommentsAfter() , sourceCode.getCommentsInside() |
context.getCommentsBefore() |
sourceCode.getCommentsBefore() |
context.getCommentsAfter() |
sourceCode.getCommentsAfter() |
context.getCommentsInside() |
sourceCode.getCommentsInside() |
context.getJSDocComment() |
sourceCode.getJSDocComment() |
context.getFirstToken() |
sourceCode.getFirstToken() |
context.getFirstTokens() |
sourceCode.getFirstTokens() |
context.getLastToken() |
sourceCode.getLastToken() |
context.getLastTokens() |
sourceCode.getLastTokens() |
context.getTokenAfter() |
sourceCode.getTokenAfter() |
context.getTokenBefore() |
sourceCode.getTokenBefore() |
context.getTokenByRangeStart() |
sourceCode.getTokenByRangeStart() |
context.getTokens() |
sourceCode.getTokens() |
context.getTokensAfter() |
sourceCode.getTokensAfter() |
context.getTokensBefore() |
sourceCode.getTokensBefore() |
context.getTokensBetween() |
sourceCode.getTokensBetween() |
context.parserServices |
sourceCode.parserServices |
To address: Following the recommendations in the blog post.
Related Issues(s): #16999, #13481
ESLint v9.0.0 removes the deprecated sourceCode.getComments()
method.
To address: Replace with sourceCode.getCommentsBefore()
, sourceCode.getCommentsAfter()
, or sourceCode.getCommentsInside()
.
Related Issues(s): #14744
ESLint v9.0.0 drops support for function-style rules. Function-style rules are rules created by exporting a function rather than an object with a create()
method. This rule format was deprecated in 2016.
To address: Update your rules to the most recent rule format.
The eslint-plugin/prefer-object-rule rule can help enforce the usage of object-style rules and autofix any remaining function-style rules.
Related Issues(s): #14709
As of ESLint v9.0.0, an error will be thrown if any options are passed to a rule that doesn't specify meta.schema
property.
To address:
- If your rule expects options, set
meta.schema
property to a JSON Schema format description of the rule’s options. This schema will be used by ESLint to validate configured options and prevent invalid or unexpected inputs to your rule. - If your rule doesn't expect any options, there is no action required. This change ensures that end users will not mistakenly configure options for rules that don't expect options.
- (not recommended) you can also set
meta.schema
tofalse
to disable this validation, but it is highly recommended to provide a schema if the rule expects options and omit the schema (or set[]
) if the rule doesn't expect options so that ESLint can ensure that your users' configurations are valid.
The eslint-plugin/require-meta-schema rule can help enforce that rules have schemas when required.
Related Issues(s): #14709
As announced in our blog post, the temporary FlatRuleTester
class has been renamed to RuleTester
, while the RuleTester
class from v8.x has been removed. Additionally, the FlatRuleTester
export from eslint/use-at-your-own-risk
has been removed.
To address: Update your rule tests to use the new RuleTester
. To do so, here are some of the common changes you'll need to make:
-
Be aware of new defaults for
ecmaVersion
andsourceType
. By default,RuleTester
uses the flat config default ofecmaVersion: "latest"
andsourceType: "module"
. This may cause some tests to break if they were expecting the old default ofecmaVersion: 5
andsourceType: "script"
. If you'd like to use the old default, you'll need to manually specify that in yourRuleTester
like this:// use eslintrc defaults const ruleTester = new RuleTester({ languageOptions: { ecmaVersion: 5, sourceType: "script" } });
-
Change
parserOptions
tolanguageOptions
. If you're settingecmaVersion
orsourceType
on your tests, move those fromparserOptions
tolanguageOptions
, like this:ruleTester.run("my-rule", myRule, { valid: [ { code: "foo", parserOptions: { ecmaVersion: 6 } } ] }); // becomes ruleTester.run("my-rule", myRule, { valid: [ { code: "foo", languageOptions: { ecmaVersion: 6 } } ] });
-
Translate other config keys. Keys such as
env
andparser
that used to run on the eslintrc config system must be translated into the flat config system. Please refer to the Configuration Migration Guide for details on translating other keys you may be using.
Related Issues(s): #13481
In order to aid in the development of high-quality custom rules that are free from common bugs, ESLint v9.0.0 implements several changes to RuleTester
:
- Suggestion messages must be unique. Because suggestions are typically displayed in an editor as a dropdown list, it's important that no two suggestions for the same lint problem have the same message. Otherwise, it's impossible to know what any given suggestion will do. This additional check runs automatically.
- Suggestions must generate valid syntax. In order for rule suggestions to be helpful, they need to be valid syntax.
RuleTester
now parses the output of suggestions using the same language options as thecode
value and throws an error if parsing fails.
To address: Run your rule tests using RuleTester
and fix any errors that occur. The changes you'll need to make to satisfy RuleTester
are compatible with ESLint v8.x.
Related Issues(s): #15735, #16908
As announced in our blog post, the temporary FlatESLint
class has been renamed to ESLint
, while the ESLint
class from v8.x has been renamed to LegacyESLint
.
To address: If you are currently using the ESLint
class, verify that your tests pass using the new ESLint
class. Not all of the old options are supported, so you may need to update the arguments passed to the constructor. See the Node.js API Reference for details.
If you still need the v8.x ESLint
functionality, use the LegacyESLint
class like this:
const { LegacyESLint } = require("eslint/use-at-your-own-risk");
Related Issues(s): #13481