-
-
Notifications
You must be signed in to change notification settings - Fork 4.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
that's looking good to me - thanks for the clarification!
|
||
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM, just one typo.
Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com>
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
configs
key 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