Skip to content

Commit 5139800

Browse files
docs: document ESLint migration codemods in v9 and v10 guides (#20980)
* docs: document ESLint migration codemods in v9 and v10 guides Add codemod usage sections and cross-reference applicable breaking changes with official @eslint codemods from the Codemod Registry. * Update docs/src/use/migrate-to-10.0.0.md Co-authored-by: lumir <[email protected]> * Update migration guide for ESLint v10.0.0 Removed unused import statement and updated content for ESLint v10.0.0 migration guide. * use direct link instead of shortlint Co-authored-by: lumir <[email protected]> * Remove Table of Contents from migrate-to-9.0.0.md Removed Table of Contents section from migration guide. * Apply suggestions from code review Co-authored-by: lumir <[email protected]> * docs: split codemod migration guidance * docs: fix migration guide formatting * Update docs/src/use/migrate-to-9.0.0.md Co-authored-by: lumir <[email protected]> * Update docs/src/use/migrate-to-10.0.0.md Co-authored-by: lumir <[email protected]> * Update docs/src/use/migrate-to-9.0.0.md Co-authored-by: lumir <[email protected]> * Update docs/src/use/migrate-to-9.0.0.md Co-authored-by: lumir <[email protected]> * Update docs/src/use/migrate-to-9.0.0.md Co-authored-by: lumir <[email protected]> * Update docs/src/use/migrate-to-9.0.0.md Co-authored-by: lumir <[email protected]> * docs: address PR review feedback on v9 codemod coverage Incorporate amirabbas-gh's review comments to improve codemod accuracy, remove unrelated callouts, and add custom-rules usage caveats. * Update docs/src/use/migrate-to-10.0.0.md Co-authored-by: lumir <[email protected]> * remove the extra comments * fix: apply prettier formatting to migrate-to-10.0.0.md --------- Co-authored-by: lumir <[email protected]>
1 parent 833ec10 commit 5139800

2 files changed

Lines changed: 125 additions & 12 deletions

File tree

‎docs/src/use/migrate-to-10.0.0.md‎

Lines changed: 38 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,25 @@ eleventyNavigation:
99

1010
ESLint v10.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.
1111

12+
To help with this migration, ESLint provides migration codemods to automate many of the changes described in this guide. All official ESLint codemods are available in the [eslint/codemods](https://github.com/eslint/codemods) repository and through the [Codemod Registry](https://app.codemod.com/registry?q=scope%3Aeslint).
13+
14+
## Use migration codemods
15+
16+
The `@eslint/v9-to-v10` codemod upgrades ESLint projects from v9 to v10. It includes four individual codemods that can also be run independently:
17+
18+
- `@eslint/v9-to-v10-config`: Remove legacy env vars and CLI flags
19+
- `@eslint/v9-to-v10-custom-rules`: Replace removed `context` and `SourceCode` methods
20+
- `@eslint/v9-to-v10-ruletester`: Clean up `RuleTester` test cases
21+
- `@eslint/v9-to-v10-linter-api`: Fix `Linter`/`ESLint` API usage
22+
23+
```shell
24+
npx codemod @eslint/v9-to-v10
25+
```
26+
27+
Learn more in the [Codemod Registry](https://app.codemod.com/registry?q=scope%3Aeslint).
28+
29+
Codemods are a starting point. Review the changes and consult the breaking changes below for anything the codemods do not cover.
30+
1231
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.
1332

1433
## Table of Contents
@@ -82,9 +101,11 @@ Three new rules have been enabled in `eslint:recommended`:
82101

83102
In ESLint v9, the alternate config lookup behavior could be enabled with the `v10_config_lookup_from_file` feature flag. This behavior made ESLint locate `eslint.config.*` by starting from the directory of each linted file and searching up towards the filesystem root. In ESLint v10.0.0, this behavior is now the default and the `v10_config_lookup_from_file` flag has been removed. Attempting to use this flag will now result in an error.
84103

104+
**Codemod:** Use the [@eslint/v9-to-v10-config](#use-migration-codemods) codemod to remove legacy flags from your setup.
105+
85106
**To address:**
86107

87-
- Remove any usage of the flag in your setup:
108+
- Remove legacy flags manually:
88109
- CLI: remove `--flag v10_config_lookup_from_file`.
89110
- Environment: remove `v10_config_lookup_from_file` from `ESLINT_FLAGS`.
90111
- API: remove `"v10_config_lookup_from_file"` from the `flags` array passed to `new ESLint()` or `new Linter()`.
@@ -98,9 +119,11 @@ ESLint v9 introduced a [new default configuration format](./configure/configurat
98119

99120
Starting with ESLint v10.0.0, the old configuration format is no longer supported.
100121

122+
**Codemod:** Use the [@eslint/v9-to-v10](#use-migration-codemods) codemod to automate much of this migration. Use the [@eslint/v9-to-v10-linter-api](#use-migration-codemods) codemod to update deprecated `FlatESLint` and `LegacyESLint` usage.
123+
101124
**To address:**
102125

103-
- Follow the instructions in the [configuration migration guide](./configure/migration-guide).
126+
- Or follow the instructions in the [configuration migration guide](./configure/migration-guide).
104127
- Be aware that the deprecated APIs `FlatESLint` and `LegacyESLint` have been removed. Always use `ESLint` instead.
105128
- The `configType` option of the `Linter` class can no longer be set to `"eslintrc"`. Remove the option to use the new configuration format.
106129

@@ -267,7 +290,9 @@ This change should not require any action for most users. However, if you are us
267290

268291
In ESLint v10.0.0, the deprecated `type` property in errors of invalid test cases for rules has been removed. Using the `type` property in test cases now throws an error.
269292

270-
**To address:** Remove the `type` property from error objects in invalid test cases.
293+
**Codemod:** Use the [@eslint/v9-to-v10-ruletester](#use-migration-codemods) codemod to automate this change.
294+
295+
**To address:** Remove the `type` property from error objects in invalid test cases manually.
271296

272297
**Related issue(s):** [#19029](https://github.com/eslint/eslint/issues/19029)
273298

@@ -336,6 +361,8 @@ In ESLint v9.x, we deprecated the following [methods](https://eslint.org/blog/20
336361

337362
In ESLint v10.0.0, all of these members have been removed.
338363

364+
**Codemod:** Use the [@eslint/v9-to-v10-custom-rules](#use-migration-codemods) codemod to automate this change.
365+
339366
**To address:** In your custom rules, make the following changes:
340367

341368
| **Removed on `context`** | **Replacement on `context`** |
@@ -375,6 +402,8 @@ The following deprecated `SourceCode` methods have been removed in ESLint v10.0.
375402

376403
These methods have been deprecated for multiple major versions and were primarily used by deprecated formatting rules and internal ESLint utilities. Custom rules using these methods must be updated to use their modern replacements.
377404

405+
**Codemod:** Use the [@eslint/v9-to-v10-custom-rules](#use-migration-codemods) codemod to automate this change.
406+
378407
**To address:** In your custom rules, make the following changes:
379408

380409
| **Removed on `SourceCode`** | **Replacement** |
@@ -412,14 +441,18 @@ const validTestCases = [
412441
ruleTester.run("rule-id", rule, { valid: validTestCases, invalid: [] });
413442
```
414443

415-
**To address:** Remove any `errors`/`output` properties from valid test cases.
444+
**Codemod:** Use the [@eslint/v9-to-v10-ruletester](#use-migration-codemods) codemod to automate this change.
445+
446+
**To address:** Remove any `errors`/`output` properties from valid test cases manually.
416447

417448
**Related issue(s):** [#18960](https://github.com/eslint/eslint/issues/18960)
418449

419450
## <a name="lintmessage-nodetype-removed"></a> Removal of `nodeType` property in `LintMessage` objects
420451

421452
In ESLint v10.0.0, the deprecated `nodeType` property on `LintMessage` objects has been removed. This affects consumers of the Node.js API (for example, custom formatters and editor/tool integrations) that previously relied on `message.nodeType`.
422453

423-
**To address:** Remove all usages of `message.nodeType` in your integrations and formatters.
454+
**Codemod:** Use the [@eslint/v9-to-v10-linter-api](#use-migration-codemods) codemod to automate this change.
455+
456+
**To address:** Remove all usages of `message.nodeType` in your integrations and formatters manually.
424457

425458
**Related issue(s):** [#19029](https://github.com/eslint/eslint/issues/19029)

0 commit comments

Comments
 (0)