docs: Plugin flat config migration guide #17640
Conversation
✅ Deploy Preview for docs-eslint ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
There was a problem hiding this comment.
The thing that's missing from my POV is how a plugin/config package should support both .eslintrc and flat configs.
Whilst, yes, v9 will switch the default - I have no doubt that there will be a long-tail of users that take a long time to (a) upgrade to v9 and (b) migrate to flat configs.
If we switch our configs over to only support flat configs then the majority of our users will be "left in the lurch" and thus will be stuck.
For example I know that at Canva or at Meta - migrating the eslint config would likely be a multi-week project given how many overrides there are - it will take a lot of testing to validate the migration is 1:1. Such a project requires prioritisation and scheduling which can delay it for quite some time.
So to summarise - I think these docs need to answer the question "how can I support flat configs and legacy configs simultaneously?"
Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com>
|
@bradzacher updated. |
|
|
||
| 1. **Export a CommonJS entrypoint.** The old configuration system cannot load plugins that are published only in ESM format. If your source code is in ESM, then you'll need to use a bundler that can generate a CommonJS version and use the [`exports`](https://nodejs.org/api/packages.html#package-entry-points) key in your `package.json` file to ensure the CommonJS version can be found by Node.js. | ||
| 1. **Keep the `environments` key.** If your plugin exports custom environments, you should keep those as they are and also export the equivalent flat configs as described above. The `environments` key is ignored when ESLint is running in flat config mode. | ||
| 1. **Export both eslintrc and flat configs.** The `configs` key is only validated when a config is used, so you can provide both formats of configs in the `configs` key. We recommend that you append older format configs with `-legacy` to make it clear that these configs will not be supported in the future. For example, if your primary config is called `recommended` and is in flat config format, then you can also have a config named `recommended-legacy` that is the eslintrc config format. |
There was a problem hiding this comment.
I guess delineating the config name with -legacy is probably the absolute best way to ensure that you can keep the backwards compat and cleanly define both configs without muddling the new vs old keys and such.
mdjermanovic
added
the
accepted
Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com>
This comment was marked as off-topic.
This comment was marked as off-topic.
Prerequisites checklist
What is the purpose of this pull request? (put an "X" next to an item)
[x] Documentation update
[ ] Bug fix (template)
[ ] New rule (template)
[ ] Changes an existing rule (template)
[ ] Add autofix to a rule
[ ] Add a CLI option
[ ] Add something to the core
[ ] Other, please explain:
What changes did you make? (Give an overview)
Added a migration guide for plugins to implement flat config. This focuses on the
configskey but also touches on everything else that plugins can export.Fixes #17242
Is there anything you'd like reviewers to focus on?
Did I miss any details? Do the examples make sense?
ping @bradzacher @JoshuaKGoldberg