Best practice for flat configs: export an object or an array?

[bmish]

I've noticed that flat configs are sometimes exported by plugins as arrays and sometimes as objects. Arrays are usually used when part of the config needs to be applied to specific files (especially to customize what rules/config apply to test files, TypeScript files, etc). Here's an example of both kinds of configs:

// configs/object-config.js

module.exports = {
  rules: { /* ... */ }
};

// configs/array-config.js

module.exports = [
  { rules: { /* ... */ }, }
  { files: ['tests/**/*.js', rules: { /* ... */ } },
];

// eslint.config.js
const objectConfig = require("eslint-plugin-example/configs/object-config");
const arrayConfig = require("eslint-plugin-example/configs/array-config");

module.exports = [
    objectConfig,
   ...arrayConfig,
];

As an ESLint user, it's not always obvious whether a plugin's config is exported as an array or object. Compared to legacy config where extends: ['plugin:example/recommended'] was the only way to use a config named recommended, you now have to research whether including config or ...config is correct. Some plugins may choose to document this in their readme and some may not.

Furthermore, you'll likely end up with a mix of object and array configs in your eslint.config.js, and this can get a bit messy, especially when needing to manipulate configs (in the case you want to override some properties such as what files one applies to).

And what happens when a plugin needs to add what used to be called an "override" to a config? The config would need to change from an object to an array. Should this be considered a breaking change since consumers would need to update their syntax for using the config?

I've seen the ESLint documentation generally shows configs exported as objects and hasn't mentioned configs exported as arrays to my knowledge.

So are plugin authors just supposed export configs as objects or arrays as needed? The only alternative I can think of is to suggest that configs always be exported arrays so users can reliably use ...config for a consistent importing experience in eslint.config.js, and for future-proofing in the event the config needs to become an array later without necessitating a breaking change.

If there's no general recommendation around this and plugins are welcome to use whatever style they prefer or need, are we just expecting plugins to document in their readme how to use their configs? I wonder if there are any guidelines or other experience improvements we can offer so that users aren't frequently tripping over this when trying to adopt a new config.

CC: @aladdin-add

[aladdin-add]

for plugins, imho, it's a best practice to export an object, not an array. For the most part, the config of a plugin is a config for some of its own rules.

for shared configs, it may be exporting an object/array - it should be described in its documentation.

[aladdin-add]

I assume you had encountered it in eslint-plugin-n's flat/mixed-esm-and-cjs config:
https://github.com/eslint-community/eslint-plugin-n/blob/b075568b34b45454d655ab1fc91f164a6b59f1b4/lib/index.js#L69-L73

the problem is there is no way to rewrite it to an object (it's possible in the eslintrc, using overrides). I think the usage like this, should be well-documented and highlighted in the docs.

[bmish]

Yes, I did encounter that one, and many other plugins I've worked with have used overrides in a config, especially for customizing things for test files or TypeScript files, which is why I'm worried this inconsistency will be a common problem.

[nzakas]

There is no best practice, really. Just export what makes sense and make sure you have provided documentation on how to use it.