docs: how to author plugins with configs that extend other configs #18753
Conversation
It's not immediately clear from the current documentation how authors should migrate configs that extend other configs. According to the [full documentation][1], an array is actually expected, which isn't clear in the migration documentation. This change updates the documentation to include an array example, and links back to the full documentation. [1]: https://eslint.org/docs/latest/extend/plugins#configs-in-plugins
✅ Deploy Preview for docs-eslint ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
| // the config referenced by example/recommended | ||
| extendedConfig: [ |
There was a problem hiding this comment.
If this config will be imported as example.configs.recommended it should be named recommended, not extendedConfig. Otherwise, it should be imported as example.configs.extendedConfig in the example file below, and in the legacy config system it would be referenced by example/extendedConfig.
| // the config referenced by example/recommended | |
| extendedConfig: [ | |
| // the config referenced by example/recommended | |
| recommended: [ |
There was a problem hiding this comment.
It is already imported as example.configs.extendedConfig...?
There was a problem hiding this comment.
In that case, can we remove the comment that says referenced by example/recommended since that's a different config in this example?
There was a problem hiding this comment.
Aha good catch. Bad copy/paste.
| }; | ||
| ``` | ||
|
|
||
| You should update your documentation so your plugin users know how to reference the exported configs. If your config is an array, consumers will have to spread it: |
There was a problem hiding this comment.
I'd recommend splitting this into two separate examples, one that shows spreading and one that doesn't, otherwise the last sentence here doesn't lead logically to the example.
There was a problem hiding this comment.
I kind of wanted them side-by-side to show that you may have some configs that shouldn't be spread, and some that should. Will tweak the copy, and if you still want it split after that copy tweak I can do that.
- fix quote style - remove stale comment - clarify copy on spreading
| You should update your documentation so your plugin users know how to reference the exported configs. If your config is an array, consumers will have to spread it: | ||
| You should update your documentation so your plugin users know how to reference the exported configs. | ||
|
|
||
| If your config is an object, consumers should not spread it; and if it's an array, they should: |
There was a problem hiding this comment.
This still implies that the following example shows just how to spread, and the verbiage is more confusing. Maybe something like this?
| If your config is an object, consumers should not spread it; and if it's an array, they should: | |
| If your exported config is an object, then your users can insert it directly into the config array; if your exported config is an array, then your users should use the spread operator (`...`) to insert the array's items into the config array. Here's an example with both an object config and an array config: |
| export default [ | ||
| example.configs.recommended, // Object, so don't spread | ||
| ...example.configs.extendedConfig, // Array, so needs spreading | ||
| ]; |
There was a problem hiding this comment.
Just a hint that if you use [].concat() to extend the configs, you don't need to care if they are arrays or not.
export default [].concat(
example.configs.recommended,
example.configs.extendedConfig,
);also:
export default [
example.configs.recommended,
example.configs.extendedConfig,
].flat();There was a problem hiding this comment.
I know, I also mentioned .flat() in my original issue.
It was just unclear to me from these migration docs if a plugin author could expect consumers to have to differentiate between different config styles (object vs array).
There was a problem hiding this comment.
Yeah, when it's explicitly documented, users don't have to guess or account for both alternatives.
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)
It's not immediately clear from the current documentation how authors should migrate configs that extend other configs.
According to the full documentation, an array is actually expected, which isn't clear in the migration documentation.
This change updates the documentation to include an array example, and links back to the full documentation.
Is there anything you'd like reviewers to focus on?