Change Request: Standardized export of flat configs to enable programmatic detection

[bmish]

ESLint version

8.56.0

What problem do you want to solve?

ESLint configs have traditionally been exported by ESLint plugins under a standard configs object (alongside the rules object). This has allowed tooling like eslint-doc-generator and lintbase.com to automatically detect/analyze configs and generate documentation regarding them including the list of configs, which rules belong to which configs, etc.

New flat configs can be exported in a variety of ways, including as an arbitrary file export from the plugin, such as require('eslint-plugin-ember/configs/recommended') in this example I worked on, and not necessarily in the configs object exported by the plugin.

For existing plugins that want to support both legacy and flat versions of their configs while maintaining backwards-compatability, I've typically seen them leave the configs object for legacy configs, and add file exports for the new flat configs.

To my knowledge, since there aren't strict requirements around how or where flat configs are exported from, the user has to manually look up in the plugin's README to find out what the configs are and how exactly to import and use them (including whether they are arrays or objects). As you can imagine, depending on the README to discover configs is not conducive to automated tooling.

What do you think is the correct solution?

Note: See updated proposal in: #18095 (comment)

Could there be a convention or requirement for how plugins should export flat configs? Presumably, this would keep legacy config exporting the same through the configs object for backwards-compatability so plugins can support both config types, at least for some time.

One idea is to require or suggest plugins to export a new configurations object containing a mapping of config name to each loaded flat config.

And what about recommendations around the direct file path entrypoint for exporting flat configs? I've seen plugins using eslint-plugin-example/configs/config-name or variations of this. Perhaps we could at least recommend a path format.

Ideally, any convention or requirement would enable programmatic discoverability of flat configs, with the added benefit of simply making it easier to use flat configs.

Participation

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

Additional comments

Related:

• Support ESLint flat config bmish/eslint-doc-generator#376

[mdjermanovic]

We could recommend a certain way of exporting configurations from plugins, but I don't think we could enforce it because ESLint doesn't load configurations from plugins.

[nzakas]

As a reminder: when you move an issue to "Feedback Needed" please mention @eslint/eslint-team to ensure people get notifications.

[nzakas]

I don't have any strong feelings around this. To me, the flexibility to be able to create your package in whatever structure you want is part of the selling point of flat config (and something people asked for in eslintrc frequently).

If we're going to recommend exporting an object, then I think it needs to be configs to go along with the existing plugin structure.

If we're going to recommend string imports then package-name/configs/config-name makes sense to me.

[JoshuaKGoldberg]

I'm in favor of establishing a recommendation. I think there's value both in allowing people to be flexible and establishing alignment guidelines for programmatic usage. 👍

[bmish]

Thinking about this some more, I agree with @nzakas that utilizing the existing configs exported object makes sense.

Ideally, all configs would be represented in this configs object, as they always have been, and we wouldn't need individual string exports like package-name/configs/config-name.

The reason some plugins have resorted to string exports is because they want to maintain the same name for their configs, e.g. the recommended config is available in legacy format at configs.recommended through the original configs object or in flat format at package-name/configs/recommended (qunit example, ember example).

Other plugins (like eslint-plugin-unicorn) have named their flat configs with flat/ so they can be used like configs['flat/recommended'] from the standard configs object.

Both of these approaches work, yet I'd consider them temporary solutions. String exports are not ideal because they aren't discoverable in the standard configs object. flat/ prefixed config naming will be redundant once flat is the only config system.

Out of both of these approaches, I would recommend the flat/ prefixing approach as it has better discoverability for tooling and reuses the existing configs object instead of introducing additional exports.

But regardless of which approach is chosen, I would recommend plugins to eventually remove the string exports or flat/ prefixing as a breaking change in a subsequent major version. If the major version comes during ESLint v9, then the legacy configs can just be suffixed with -legacy like recommended-legacy (or prefixed with legacy/) to continue supporting them. If the major version comes after ESLint v10, then the legacy configs can be removed entirely. So the end state should be that configs are all back in the exported configs object with the original naming like recommended.

Recommending standard config prefixes and suffixes would also enable us to detect which config is legacy vs. flat and thus whether a plugin supports flat config, as in these easily-distinguishable examples:

• recommended (legacy) and flat/recommended
• legacy-recommended and recommended (flat)

Perhaps we can include these recommendations in the Configuration Files (New) or Configuration Migration Guide docs in a section on backwards compatibility / how to support both flat and legacy config / plugins exports.

[nzakas]

Out of both of these approaches, I would recommend the flat/ prefixing approach as it has better discoverability for tooling and reuses the existing configs object instead of introducing additional exports.

I'd prefer not to use the name "flat" at all. The only reason we talk about flat config now is to disambiguate it from eslintrc, but in the future, there will be no reason to say anything other than "config". This is why we recommend the "-legacy" suffix for eslintrc configs.

Regarding discoverability: it's trivial to determine if something is a flat config vs. an eslintrc config, so I'm not sure if it's important to encode that information into the name for tooling purposes. There are certain keys that exist at the top level in eslintrc that aren't there in flat config. Could we not just use that to determine what kind of config it is?