eslint/docs/user-guide/migrating-to-8.0.0.md

   1 # Migrating to v8.0.0
   2
   3 ESLint v8.0.0 is a major release of ESLint. We have made a few breaking changes in this release. This guide is intended to walk you through the breaking changes.
   4
   5 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.
   6
   7 ## Table of Contents
   8
   9 ### Breaking changes for users
  10
  11 - [Node.js 10, 13, and 15 are no longer supported](#drop-old-node)
  12 - [Removed `codeframe` and `table` formatters](#removed-formatters)
  13 - [`comma-dangle` rule schema is stricter](#comma-dangle)
  14 - [Unused disable directives are now fixable](#directives)
  15 - [`eslint:recommended` has been updated](#eslint-recommended)
  16
  17 ### Breaking changes for plugin developers
  18
  19 - [Node.js 10, 13, and 15 are no longer supported](#drop-old-node)
  20 - [Rules require `meta.hasSuggestions` to provide suggestions](#suggestions)
  21 - [Rules require `meta.fixable` to provide fixes](#fixes)
  22 - [`SourceCode#getComments()` fails in `RuleTester`](#get-comments)
  23 - [Changes to shorthand property AST format](#ast-format)
  24
  25 ### Breaking changes for integration developers
  26
  27 - [Node.js 10, 13, and 15 are no longer supported](#drop-old-node)
  28 - [The `CLIEngine` class has been removed](#remove-cliengine)
  29 - [The `linter` object has been removed](#remove-linter)
  30 - [The `/lib` entrypoint has been removed](#remove-lib)
  31
  32 ---
  33
  34 ## <a name="drop-old-node"></a> Node.js 10, 13, and 15 are no longer supported
  35
  36 Node.js 10, 13, 15 all reached end of life either in 2020 or early 2021. ESLint is officially dropping support for these versions of Node.js starting with ESLint v8.0.0. ESLint now supports the following versions of Node.js:
  37
  38 - Node.js 12.22 and above
  39 - Node.js 14 and above
  40 - Node.js 16 and above
  41
  42 **To address:** Make sure you upgrade to at least Node.js `12.22.0` when using ESLint v8.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 7 until you are able to upgrade Node.js.
  43
  44 **Related issue(s):** [#14023](https://github.com/eslint/eslint/issues/14023)
  45
  46 ## <a name="removed-formatters"></a> Removed `codeframe` and `table` formatters
  47
  48 ESLint v8.0.0 has removed the `codeframe` and `table` formatters from the core. These formatters required dependencies that weren't used anywhere else in ESLint, and removing them allows us to reduce the size of ESLint, allowing for faster installation.
  49
  50 **To address:** If you are using the `codeframe` or `table` formatters, you'll need to install the standalone [`eslint-formatter-codeframe`](https://github.com/fregante/eslint-formatter-codeframe) or [`eslint-formatter-table`](https://github.com/fregante/eslint-formatter-table) packages, respectively, to be able to use them in ESLint v8.0.0.
  51
  52 **Related issue(s):** [#14277](https://github.com/eslint/eslint/issues/14277), [#14316](https://github.com/eslint/eslint/pull/14316)
  53
  54
  55 ## <a name="comma-dangle"></a> `comma-dangle` rule schema is stricter
  56
  57 In ESLint v7.0.0, the `comma-dangle` rule could be configured like this without error:
  58
  59 ```json
  60 {
  61     "rules": {
  62         "comma-dangle": ["error", "never", { "arrays": "always" }]
  63     }
  64 }
  65 ```
  66
  67 With this configuration, the rule would ignore the third element in the array because only the second element is read. In ESLint v8.0.0, this configuration will cause ESLint to throw an error.
  68
  69 **To address:** Change your rule configuration so that there are only two elements in the array, and the second element is either a string or an object, such as:
  70
  71 ```jsonc
  72 {
  73     "comma-dangle": ["error", "never"],
  74     // or
  75     "comma-dangle": ["error", {
  76         "arrays": "never",
  77         "objects": "never",
  78         "imports": "never",
  79         "exports": "never",
  80         "functions": "never"
  81     }]
  82 }
  83 ```
  84
  85 **Related issue(s):** [#13739](https://github.com/eslint/eslint/issues/13739)
  86
  87 ## <a name="directives"></a> Unused disable directives are now fixable
  88
  89 In ESLint v7.0.0, using both `--report-unused-disable-directives` and `--fix` on the command line would fix only rules but leave unused disable directives in place. In ESLint v8.0.0, this combination of command-line options will result in the unused disable directives being removed.
  90
  91 **To address:** If you are using `--report-unused-disable-directives` and `--fix` together on the command line, and you don't want unused disable directives to be removed, add `--fix-type problem,suggestion,layout` as a command line option.
  92
  93 **Related issue(s):** [#11815](https://github.com/eslint/eslint/issues/11815)
  94
  95 ## <a name="eslint-recommended"></a> `eslint:recommended` has been updated
  96
  97 Four new rules have been enabled in the `eslint:recommended` preset.
  98
  99 - [`no-loss-of-precision`](https://eslint.org/docs/rules/no-loss-of-precision)
 100 - [`no-nonoctal-decimal-escape`](https://eslint.org/docs/rules/no-nonoctal-decimal-escape)
 101 - [`no-unsafe-optional-chaining`](https://eslint.org/docs/rules/no-unsafe-optional-chaining)
 102 - [`no-useless-backreference`](https://eslint.org/docs/rules/no-useless-backreference)
 103
 104 **To address:** Fix errors or disable these rules.
 105
 106 **Related issue(s):** [#14673](https://github.com/eslint/eslint/issues/14673)
 107
 108
 109 ## <a name="suggestions"></a> Rules require `meta.hasSuggestions` to provide suggestions
 110
 111 In ESLint v7.0.0, rules that [provided suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions) did not need to let ESLint know. In v8.0.0, rules providing suggestions need to set their `meta.hasSuggestions` to `true`. This informs ESLint that the rule intends to provide suggestions. Without this property, any attempt to provide a suggestion will result in an error.
 112
 113 **To address:** If your rule provides suggestions, add `meta.hasSuggestions` to the object, such as:
 114
 115 ```js
 116 module.exports = {
 117     meta: {
 118         hasSuggestions: true
 119     },
 120     create(context) {
 121         // your rule
 122     }
 123 };
 124 ```
 125
 126 The [eslint-plugin/require-meta-has-suggestions](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/require-meta-has-suggestions.md) rule can automatically fix and enforce that your rules are properly specifying `meta.hasSuggestions`.
 127
 128 **Related issue(s):** [#14312](https://github.com/eslint/eslint/issues/14312)
 129
 130 ## <a name="fixes"></a> Rules require `meta.fixable` to provide fixes
 131
 132 In ESLint v7.0.0, rules that were written as a function (rather than object) were able to provide fixes. In ESLint v8.0.0, only rules written as an object are allowed to provide fixes and must have a `meta.fixable` property set to either `"code"` or `"whitespace"`.
 133
 134 **To address:** If your rule makes fixes and is written as a function, such as:
 135
 136 ```js
 137 module.exports = function(context) {
 138     // your rule
 139 };
 140 ```
 141
 142 Then rewrite your rule in this format:
 143
 144 ```js
 145 module.exports = {
 146     meta: {
 147         fixable: "code" // or "whitespace"
 148     },
 149     create(context) {
 150         // your rule
 151     }
 152 };
 153 ```
 154
 155 The [eslint-plugin/require-meta-fixable](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/require-meta-fixable.md) rule can automatically fix and enforce that your rules are properly specifying `meta.fixable`.
 156
 157 The [eslint-plugin/prefer-object-rule](https://github.com/not-an-aardvark/eslint-plugin-eslint-plugin/blob/master/docs/rules/prefer-object-rule.md) rule can automatically fix and enforce that your rules are written with the object format instead of the deprecated function format.
 158
 159 See the [rule documentation](https://eslint.org/docs/developer-guide/working-with-rules) for more information on writing rules.
 160
 161 **Related issue(s):** [#13349](https://github.com/eslint/eslint/issues/13349)
 162
 163 ## <a name="get-comments"></a> `SourceCode#getComments()` fails in `RuleTester`
 164
 165 Back in ESLint v4.0.0, we deprecated `SourceCode#getComments()`, but we neglected to remove it. Rather than removing it completely in v8.0.0, we are taking the intermediate step of updating `RuleTester` to fail when `SourceCode#getComments()` is used inside of a rule. As such, all existing rules will continue to work, but when the developer runs tests for the rule there will be a failure.
 166
 167 The `SourceCode#getComments()` method will be removed in v9.0.0.
 168
 169 **To address:** If your rule uses `SourceCode#getComments()`, please use [`SourceCode#getCommentsBefore()`, `SourceCode#getCommentsAfter()`, or `SourceCode#getCommentsInside()`](https://eslint.org/docs/developer-guide/working-with-rules#sourcecodegetcommentsbefore-sourcecodegetcommentsafter-and-sourcecodegetcommentsinside).
 170
 171 **Related issue(s):** [#14744](https://github.com/eslint/eslint/issues/14744)
 172
 173 ## <a name="ast-format"></a> Changes to shorthand property AST format
 174
 175 ESLint v8.0.0 includes an upgrade to Espree v8.0.0 to support new syntax. This Espree upgrade, in turn, contains an upgrade to Acorn v8.0.0, which changed how shorthand properties were represented in the AST. Here's an example:
 176
 177 ```js
 178 const version = 8;
 179 const x = {
 180     version
 181 };
 182 ```
 183
 184 This code creates a property node that looks like this:
 185
 186 ```json
 187 {
 188     "type": "Property",
 189     "method": false,
 190     "shorthand": true,
 191     "computed": false,
 192     "key": {
 193         "type": "Identifier",
 194         "name": "version"
 195     },
 196     "kind": "init",
 197     "value": {
 198         "type": "Identifier",
 199         "name": "version"
 200     }
 201 }
 202 ```
 203
 204 Note that both the `key` and the `value` properties contain the same information. Prior to Acorn v8.0.0 (and therefore prior to ESLint v8.0.0), these two nodes were represented by the same object, so you could use `===` to determine if they represented the same node, such as:
 205
 206 ```js
 207 // true in ESLint v7.x, false in ESLint v8.0.0
 208 if (propertyNode.key === propertyNode.value) {
 209     // do something
 210 }
 211 ```
 212
 213 In ESLint v8.0.0 (via Acorn v8.0.0), the key and value are now separate objects and therefore no longer equivalent.
 214
 215 **To address:** If your rule makes a comparison between the key and value of a shorthand object literal property to determine if they are the same node, you'll need to change your code in one of two ways:
 216
 217 1. Use `propertyNode.shorthand` to determine if the property is a shorthand property node.
 218 1. Use the `range` property of each node to determine if the key and value occupy the same location.
 219
 220 **Related issue(s):** [#14591](https://github.com/eslint/eslint/pull/14591#issuecomment-887733070)
 221
 222
 223 ## <a name="remove-cliengine"></a> The `CLIEngine` class has been removed
 224
 225 The `CLIEngine` class has been removed and replaced by the [`ESLint` class](https://eslint.org/docs/developer-guide/nodejs-api#eslint-class).
 226
 227 **To address:** Update your code to use the new `ESLint` class if you are currently using `CLIEngine`. The following table maps the existing `CLIEngine` methods to their `ESLint` counterparts:
 228
 229 | `CLIEngine`                                  | `ESLint`                           |
 230 | :------------------------------------------- | :--------------------------------- |
 231 | `executeOnFiles(patterns)`                   | `lintFiles(patterns)`              |
 232 | `executeOnText(text, filePath, warnIgnored)` | `lintText(text, options)`          |
 233 | `getFormatter(name)`                         | `loadFormatter(name)`              |
 234 | `getConfigForFile(filePath)`                 | `calculateConfigForFile(filePath)` |
 235 | `isPathIgnored(filePath)`                    | `isPathIgnored(filePath)`          |
 236 | `static outputFixes(results)`                | `static outputFixes(results)`      |
 237 | `static getErrorResults(results)`            | `static getErrorResults(results)`  |
 238 | `static getFormatter(name)`                  | (removed ※1)                      |
 239 | `addPlugin(pluginId, definition)`            | the `plugins` constructor option   |
 240 | `getRules()`                                 | (removed ※2)                      |
 241 | `resolveFileGlobPatterns()`                  | (removed ※3)                      |
 242
 243 - ※1 The `engine.getFormatter()` method currently returns the object of loaded packages as-is, which made it difficult to add new features to formatters for backward compatibility reasons. The new `eslint.loadFormatter()` method returns an adapter object that wraps the object of loaded packages, to ease the process of adding new features. Additionally, the adapter object has access to the `ESLint` instance to calculate default data (using loaded plugin rules to make `rulesMeta`, for example). As a result, the `ESLint` class only implements an instance version of the `loadFormatter()` method.
 244 - ※2 The `CLIEngine#getRules()` method had side effects and so was removed. If you were using `CLIEngine#getRules()` to retrieve meta information about rules based on linting results, use `ESLint#getRulesMetaForResults()` instead. If you were using `CLIEngine#getRules()` to retrieve all built-in rules, import `builtinRules` from `eslint/use-at-your-own-risk` for an unsupported API that allows access to internal rules.
 245 - ※3 Since ESLint v6.0.0, ESLint uses different logic from the `resolveFileGlobPatterns()` method to iterate files, making this method obsolete.
 246
 247 **Related issue(s):** [RFC80](https://github.com/eslint/rfcs/tree/main/designs/2021-package-exports), [#14716](https://github.com/eslint/eslint/pull/14716), [#13654](https://github.com/eslint/eslint/issues/13654)
 248
 249 ## <a name="remove-linter"></a> The `linter` object has been removed
 250
 251 The deprecated `linter` object has been removed from the ESLint package in v8.0.0.
 252
 253 **To address:** If you are using the `linter` object, such as:
 254
 255 ```js
 256 const { linter } = require("eslint");
 257 ```
 258
 259 Change your code to this:
 260
 261 ```js
 262 const { Linter } = require("eslint");
 263 const linter = new Linter();
 264 ```
 265
 266 **Related issue(s):** [RFC80](https://github.com/eslint/rfcs/tree/main/designs/2021-package-exports), [#14716](https://github.com/eslint/eslint/pull/14716), [#13654](https://github.com/eslint/eslint/issues/13654)
 267
 268 ## <a name="remove-lib"></a> The `/lib` entrypoint has been removed
 269
 270 Beginning in v8.0.0, ESLint is strictly defining its public API. Previously, you could reach into individual files such as `require("eslint/lib/rules/semi")` and this is no longer allowed. There are a limited number of existing APIs that are now available through the `/use-at-your-own-risk` entrypoint for backwards compatibility, but these APIs are not formally supported and may break or disappear at any point in time.
 271
 272 **To address:** If you are accessing rules directly through the `/lib` entrypoint, such as:
 273
 274 ```js
 275 const rule = require("eslint/lib/rules/semi");
 276 ```
 277
 278 Change your code to this:
 279
 280 ```js
 281 const { builtinRules } = require("eslint/use-at-your-own-risk");
 282 const rule = builtinRules.get("semi");
 283 ```
 284
 285 If you are accessing `FileEnumerator` directly through the `/lib` entrypoint, such as:
 286
 287 ```js
 288 const { FileEnumerator } = require("eslint/lib/cli-engine/file-enumerator");
 289 ```
 290
 291 Change your code to this:
 292
 293 ```js
 294 const { FileEnumerator } = require("eslint/use-at-your-own-risk");
 295 ```
 296
 297 **Related issue(s):** [RFC80](https://github.com/eslint/rfcs/tree/main/designs/2021-package-exports), [#14716](https://github.com/eslint/eslint/pull/14716), [#13654](https://github.com/eslint/eslint/issues/13654)