|
1 | | -# Migration from @strv/eslint-config-javascript |
| 1 | +# Migrating to flat config (ESLint v9 or >=8.56.0) |
2 | 2 |
|
3 | | -This new initiative provides all the functionality which was included in the old ESLint config package, with the only exception being the **flow** ruleset which has been removed. The `v1.0.0` versions of all packages hosted here are 1:1 compatible with the latest version of `@strv/eslint-config-javascript` (`9.2.0`), therefore no new errors or warnings should be reported after the migration. |
| 3 | +🚨 As of now (February 2024) some plugins used in these rulesets are not yet compatible with ESLint v9. While it is recommended that you upgrade your projects to the flat config format it also means that if you do, you will need to stay on ESLint v8 until all plugins are updated. |
4 | 4 |
|
5 | | -- Uninstall `@strv/eslint-config-javascript` |
6 | | -- Open your _.eslintrc.js_ file and check which rulesets you use |
7 | | -- Based on the table below, replace the rulesets in your config file with the new names |
8 | | -- Install the missing rulesets from npm |
| 5 | +--- |
9 | 6 |
|
10 | | -| Old ruleset | New ruleset | package | |
11 | | -| -------------------------------------------- | -------------------- | -------------------------------------------------------------------------- | |
12 | | -| `@strv/javascript/environments/nodejs/*` | `@strv/node/*` | [`@strv/eslint-config-node`][es-node-home] | |
13 | | -| `@strv/javascript/environments/react/*` | `@strv/react/*` | [`@strv/eslint-config-react`][es-react-home] | |
14 | | -| `@strv/javascript/environments/mocha/*` | `@strv/mocha/*` | [`@strv/eslint-config-mocha`][es-mocha-home] | |
15 | | -| `@strv/javascript/environments/typescript/*` | `@strv/typescript/*` | [`@strv/eslint-config-typescript`][es-ts-home] | |
16 | | -| `@strv/javascript/environments/flow/*` | 🔥 | Removed without replacement 😱 | |
17 | | -| `@strv/javascript/coding-styles/*` | 🔥 | Coding style rulesets are now part of the environment-specific packages ❤️ | |
| 7 | +As of ESLint v9 the way ESLint is configured is going to change dramatically. Support for this new "flat" config format has been introduced to ESLint v8.56 behind a feature flag (`ESLINT_USE_FLAT_CONFIG=true` env var). This guide will help you rewrite your config to the new format. |
18 | 8 |
|
19 | | -The following rulesets have been removed as part of the migration: |
| 9 | +## Documentation |
20 | 10 |
|
21 | | -- `@strv/javascript/environments/nodejs/v6` |
22 | | -- `@strv/javascript/environments/nodejs/v8-3` |
23 | | -- `@strv/javascript/environments/flow/*` |
24 | | -- `@strv/javascript/coding-styles/*` |
| 11 | +ESLint: https://eslint.org/docs/latest/use/configure/configuration-files-new |
25 | 12 |
|
26 | | -## Still confused? |
| 13 | +## Old way |
27 | 14 |
|
28 | | -Open an issue over at [@strv/code-quality-tools][cqt-home] or ping @robertrossmann on STRV Slack. 💪 |
| 15 | +The old system was designed to support YAML, JSON, and JavaScript configuration files. You would use a ruleset or a plugin by providing its name (a string) and ESLint would look it up and use it. Also, ESLint automatically checked known JavaScript files and you had to go the extra mile to add support for ie. TypeScript (`.ts`) or React (`.jsx`) files. |
29 | 16 |
|
30 | | -## ...but why? |
| 17 | +```js |
| 18 | +// .eslintrc.js |
31 | 19 |
|
32 | | -### More granular release cycle |
| 20 | +// Example config. Notice how it's not clear which files are going to be linted by default. |
| 21 | +// Also notice that the `extends` field is a string and ESLint needs to load that module. |
| 22 | +/** @type {import("eslint").Linter.Config} */ |
| 23 | +module.exports = { |
| 24 | + reportUnusedDisableDirectives: true, |
| 25 | + extends: [ |
| 26 | + '@strv/node/v20', |
| 27 | + '@strv/node/optional', |
| 28 | + '@strv/node/style', |
| 29 | + ], |
| 30 | + rules: { |
| 31 | + 'no-warning-comments': 'off', |
| 32 | + }, |
33 | 33 |
|
34 | | -Separating the environments into dedicated packages will reduce noise when a new version for a specific environment is released. Before, when a new rule has been added to the `nodejs` ruleset, everyone received an upgrade even if they only used the `react` ruleset and did not care about changes to the `nodejs` ruleset. With the new setup, each environment will follow its own semver release cycle. |
| 34 | + overrides: [{ |
| 35 | + files: [ |
| 36 | + '**/*.ts', |
| 37 | + '**/*.spec.ts', |
| 38 | + '**/*.e2e-spec.ts', |
| 39 | + ], |
| 40 | + extends: [ |
| 41 | + '@strv/node/v20', |
| 42 | + '@strv/node/optional', |
| 43 | + '@strv/eslint-config-typescript', |
| 44 | + '@strv/eslint-config-typescript/style', |
| 45 | + ], |
| 46 | + parserOptions: { |
| 47 | + project: './tsconfig.json', |
| 48 | + }, |
| 49 | +``` |
35 | 50 |
|
36 | | -### Not just ESLint anymore |
| 51 | +## New way |
37 | 52 |
|
38 | | -The new repository contains configurations for a bunch of other linting tools, not just ESLint. We wanted to keep all these configs under a single roof, so we decided to move the code over there. |
| 53 | +The new system has several advantages over the previous config format but it also requires a bit more effort to properly set up. Each configuration now encourages to specify the files to which it should apply and all rulesets and plugins are provided as regular imported types because the configuration now must be written in JavaScript. |
39 | 54 |
|
40 | | -[cqt-home]: https://github.com/strvcom/code-quality-tools |
41 | | -[es-node-home]: https://github.com/strvcom/code-quality-tools/tree/master/packages/eslint-config-node |
42 | | -[es-react-home]: https://github.com/strvcom/code-quality-tools/tree/master/packages/eslint-config-react |
43 | | -[es-mocha-home]: https://github.com/strvcom/code-quality-tools/tree/master/packages/eslint-config-mocha |
44 | | -[es-ts-home]: https://github.com/strvcom/code-quality-tools/tree/master/packages/eslint-config-typescript |
| 55 | +```js |
| 56 | +// eslint.config.mjs |
| 57 | + |
| 58 | +// This is a sample configuration for a TypeScript Node.js project. |
| 59 | + |
| 60 | +// All plugins, parsers and rulesets must be imported as modules |
| 61 | +import nodev20 from '@strv/eslint-config-node/v20' |
| 62 | +import nodeopt from '@strv/eslint-config-node/optional' |
| 63 | +import nodestyle from '@strv/eslint-config-node/style' |
| 64 | +import ts from '@strv/eslint-config-typescript' |
| 65 | +import tsopt from '@strv/eslint-config-typescript/optional' |
| 66 | +import tsstyle from '@strv/eslint-config-typescript/style' |
| 67 | +// Just to help us re-use the same globs multiple times |
| 68 | +const files = { |
| 69 | + ts: '**/*.ts', |
| 70 | + mjs: '**/*.mjs', |
| 71 | +} |
| 72 | + |
| 73 | +// This will allow your IDE to provide autocomplete suggestions ✨ |
| 74 | +/** @type {Array<import("eslint").Linter.FlatConfig>} */ |
| 75 | +const config = [{ |
| 76 | + linterOptions: { |
| 77 | + reportUnusedDisableDirectives: true, |
| 78 | + }, |
| 79 | + ignores: ['**/*.js', '*.d.ts', '!.*.js', 'node_modules'], |
| 80 | +}, { |
| 81 | + // First, we provide a configuration object that supplies the tsconfig path to all plugins that might need it. |
| 82 | + files: [files.ts], |
| 83 | + languageOptions: { |
| 84 | + parserOptions: { project: './tsconfig.json' }, |
| 85 | + } }, |
| 86 | +// Next, we apply all the rulesets, one by one, which we want to use for our TypeScript sources. |
| 87 | +// ⚠️ Do not apply more than one ruleset inside the same configuration object as they would not get merged correctly. |
| 88 | +{ files: [files.ts], ...nodev20 }, |
| 89 | +{ files: [files.ts], ...nodeopt }, |
| 90 | +{ files: [files.ts], ...ts }, |
| 91 | +{ files: [files.ts], ...tsopt }, |
| 92 | +{ files: [files.ts], ...tsstyle }, |
| 93 | + |
| 94 | +{ files: [files.mjs], ...nodev20 }, |
| 95 | +{ files: [files.mjs], ...nodeopt }, |
| 96 | +{ files: [files.mjs], ...nodestyle }, |
| 97 | +// Custom overrides |
| 98 | +{ files: [files.ts], |
| 99 | + rules: { |
| 100 | + 'no-warning-comments': 0, |
| 101 | + '@typescript-eslint/naming-convention': 'off', |
| 102 | + } }, |
| 103 | +] |
| 104 | + |
| 105 | +export default config |
| 106 | +``` |
0 commit comments