Really we should remove that property entirely.
Unlike the legacy system - there's no actual requirement for a flat config plugin to define anything in any particular way because the configs are consumed explicitly by the user via an import, not implicitly via eslint.

While there might not be a strict requirement, I think plugins should expose a common interface, otherwise it would be impractical to use them. The ESLint docs say:

A plugin is a JavaScript object that exposes certain properties to ESLint

• meta - information about the plugin.
• configs - an object containing named configurations.
• rules - an object containing the definitions of custom rules.
• processors - an object containing named processors.

If you plan to distribute your plugin as an npm package, make sure that the module that exports the plugin object is the default export of your package. This will enable ESLint to import the plugin when it is specified in the command line in the --plugin option.

So they do expect you to structure your plugin in a certain way.

I wanted to use the TSESLint.FlatConfig.Plugin type to ensure that I do export the plugin adhering to this structure.

I found another thing that made it impractical to use this type though. All the properties are optional, so even though I specify them, users of the plugin will see them as optional and have to do a non-null assertion. But I can use e.g. Required<...> to get around that.

So they do expect you to structure your plugin in a certain way

They don't -- meta, rules, processors are the important ones.
configs allows backwards compat with v8 but it's not necessary.
For example many plugins now are choosing NOT to do a configs prop and instead are doing a /configs export like import recommended from 'eslint-plugin-foo/configs/recommended'.

ESLint generally has recommended people export configs prop with the flat configs named recommended and the legacy configs named recommended-lgacy. Some plugins have instead chosen to name them like flat/recommended or recommended-flat so they don't need to do a breaking change.

There's no real consistency in the ecosystem right now, to be honest.

It's not required, and there may not be consistency in the ecosystem right now, but ESLint do suggest exporting configs in this specific way. The docs say:

You can bundle configurations inside a plugin by specifying them under the configs key.

And doesn't mention another way of exposing configs. Wouldn't it then make sense to have a type that matches this? Using the type/property is optional after all.

I'm just going from what I'm reading on this docs page, so you have more context about this than me, but I would think what that page describes is what the ESLint authors intends.

I realized now that using this type (TSESLint.FlatConfig.Plugin with configs set to Config | ConfigArray) as the type exported by my plugin wouldn't be very useful, as consumers of the plugin wouldn't know if configs was a single object or an array, and would get type errors when using it unless they narrowed it.

I could still us it with a satisfies clause to ensure what I export is valid though.

This is exactly the problem.
A plugin could export either an object or it could export an array. Both are considered valid - the former is the more common thing as the latter requires the user to spread - so you avoid it unless the config needs multiple elements (like ours do).

There is a lot of variance that is accepted within the ecosystem right now - so at best I'd want to specify like config?: LegacyConfig | FlatConfig | FlatConfigArray as that's what is valid and used across the ecosystem.

Maybe it would be useful to have a helper function (like tseslint.config) that you pass the config to which verifies that the type is correct and returns the type you passed in? Basically just

function plugin<T extends TSESLint.FlatConfig.Plugin>(plugin: T) {
  return plugin
}

Found the same issue with typings and to be honest it's very confusing.

I want to highlight that ESLint currently officially says that shared config in a plugin can be either object or array.

This plugin exports a recommended config that is an array with one config object. When there is just one config object, you can also export just the object without an enclosing array.

In order to use a config from a plugin in a configuration file, import the plugin and access the config directly through the plugin object. Assuming the config is an array, use the spread operator to add it into the array returned from the configuration file, like this:

// eslint.config.js
import example from "eslint-plugin-example";

export default [
    ...example.configs.recommended
];

Now, let's imaging that we have 2 shared configs:

• recommended
• recommendedTypedChecked

and I (as a developer of a plugin) want to extend recommended from recommendedTypedChecked.

In a FlatConfig format, if you need to extend one config from another, you must use arrays cause there is no extends key anymore:

If your config extends other configs, you can export an array:

const baseConfig = require("./base-config");

module.exports = {
    configs: {
        extendedConfig: [
            baseConfig,
           {
                rules: {
                    "example/rule1": "error",
                    "example/rule2": "error"
                }
            }
        ],
    },
};

Thus, if you have shared configs in a plugin and one of the shared config extends the other, there is no way except returning an array, and this exact case is completely unsupported by typescript-eslint typings right now, because only object is allowed.

So, it's practically impossible right now to have fully typed plugin object without any workaround.

Related piece of the code:

I even tried to find how typescript-eslint/eslint-plugin work with it, but it just uses ClassicConfig instead of FlatConfig at the moment.

Maybe it would be useful to have a helper function (like tseslint.config) that you pass the config to which verifies that the type is correct and returns the type you passed in? Basically just

function plugin<T extends TSESLint.FlatConfig.Plugin>(plugin: T) {
  return plugin
}

@trygveaa

this is exactly just the satisfies operator, no? plugin satisfies TSESLint.FlatConfig.Plugin

this is exactly just the satisfies operator, no? plugin satisfies TSESLint.FlatConfig.Plugin

Oh, yeah that's true. Then I guess there's no point in it.

@maks-rafalko Is there something in your response that is not addressed by the resolution for which this issue is accepting PRs (#10213 (comment))?

@kirkwaiblinger sorry, probably I didn't get neither your comment nor the comment you are referencing (for me, it doesn't sound like resolution).

Anyway, I thought suggested config?: LegacyConfig | FlatConfig | FlatConfigArray was just a pseudocode, because the current SharedConfig has completely different structure:

I'm not familiar with the codebase so don't take my words seriously, but I thought that the simplest solution could be like this:

interface SharedConfigs {
-    [key: string]: Config;
+    [key: string]: Config | ConfigArray;
}

does it makes sense? If not, then please elaborate on config?: LegacyConfig | FlatConfig | FlatConfigArray:

• how it should be used inside the type for a plugin
• why we are mixing legacy and flat configs here
• why config is singular but not plural

There is a lot of variance that is accepted within the ecosystem right now - so at best I'd want to specify like config?: LegacyConfig | FlatConfig | FlatConfigArray as that's what is valid and used across the ecosystem.

Including legacy config would mean mixing ClassicConfig and FlatConfig. Do you want to do that? The Plugin type lives inside FlatConfig so I figured it didn't really make sense to include legacy config there.

I'm not familiar with the codebase so don't take my words seriously, but I thought that the simplest solution could be like this:

This is what I have already proposed in PR #10217.

Right, exactly, all I'm getting at is that my understanding is that all parties agree that #10217 (which implements the intended meaning of #10213 (comment)) is the appropriate resolution then 👍 So I was double checking that there wasn't an additional, unaccounted-for concern raised in #10213 (comment) that we needed to hash out still. 🙂