Change Request: document flat configs in plugins

[paulius-valiunas]

ESLint version

8.42.0

What problem do you want to solve?

Current documentation page on writing plugins uses legacy configs

What do you think is the correct solution?

It should provide a useful example of how a flat config can be included in a plugin without circular imports.

Participation

• I am willing to submit a pull request for this change.

Additional comments

No response

[Rec0iL99]

Hi @paulius-valiunas, this is indeed included in our phase 4 of implementing flat config.

You can track the implementation here #13481,

[bradzacher]

Copying from #17391

Currently there is no information in the docs about how a plugin might migrate to support flat configs.

For example - one would need to migrate shared configs to the new format - but what does that look like? I know that the plugins key needs to change its form - but the existing docs still use the old form.

How should a plugin go about supporting both flat and classic configs? What's the best-practice for doing this?
For example eslint-plugin-react exports configs from the package root in the classic form, and provides imports for each config in the flat form (require('eslint-plugin-react/configs/recommended')). Is this the "best practice" way of doing it? Is there another way?

What about things like languageOptions - how can you support both languageOptions and parserOptions?

Based on my understanding - the configs will be validated for excess props - so plugins will need to duplicate the configs if they want to do things like extend other configs or provide parserOptions/languageOptions/parser.

Is there tooling to do this automatically so that plugins don't have to all implement the same copy pasted logic of "extend the classic config and rename somethings"?

I guess what I'm saying is that the user story for flat configs is well documented and planned out - but it feels like the developer story is lacking right now which makes it hard for plugins to build support.

We on @typescript-eslint have users asking for it and they're not sure how to use our plugin with the new config file. Currently our response is "use the compat tooling because we don't support it".
Without clear guidance and best practices around how we are supposed to support both worlds in a fully backwards compatible way - we don't want to take the step lest we do it wrong and have to release a new major version to undo/fixup a change.

I'm sure a lot of other plugins and community configs are in exactly the same boat.
Whether we like it or not - legacy config files are going to live on for a long time - even when ESLint drops official support for them, so the ecosystem needs solid plans and tools to continue supporting them into the future.