feat: allow flat config files to export a Promise

[mdjermanovic]

Prerequisites checklist

• I have read the contributing guidelines.

What is the purpose of this pull request? (put an "X" next to an item)

[ ] Documentation update
[ ] Bug fix (template)
[ ] New rule (template)
[ ] Changes an existing rule (template)
[ ] Add autofix to a rule
[ ] Add a CLI option
[x] Add something to the core
[ ] Other, please explain:

Fixes #16864, Fixes #16580

Officially adds support for exporting Promises from eslint.config.js files. Technically, this was already working.

Note that this doesn't mean that a config object inside the config array can be a Promise, just that project's config file can export a Promise.

What changes did you make? (Give an overview)

• Added tests.
• Updated documentation with this feature.
• Added a note that in CommonJS projects eslint.config.js must be in the CommonJS format (fixes Bug: [flat config] .mjs extension for config file #16580).

Is there anything you'd like reviewers to focus on?

[fasttime]

LGTM, thanks!

[nzakas]

LGTM. Just left a couple suggestions for clarifying the docs, but otherwise, this is good to go.

[mdjermanovic]

LGTM. Just left a couple suggestions for clarifying the docs, but otherwise, this is good to go.

Thanks! Merging now.

[ljharb]

How does this fix #16580?

[jaydenseric]

It disappointingly doesn't allow the config file to have ESM with a .mjs file extension, but I guess the logic is that people can use CJS in a .js config file and not be blocked from importing ESM, by using async dynamic imports and then the exported config would be a promise. Yuk.

[dburles]

If you're only supporting Node versions that can load and interpret ESM (correct me if I'm wrong), then why not just go with an ESM only config as originally suggested (eslint.config.mjs)? Supporting a CJS config as well as ESM seems to make very little sense.

[morganney]

Was #16580 every really a problem with ESLint?

My npm package is commonjs, with .js extensions, alongside ESM with .mjs extensions for running tests.

There is already the -c eslint.config.mjs workaround for people who define their project as CJS but then want to write their ESLint configuration in ESM.

The real problem seems to be users that define their package as CJS but then write their source in ESM 🙃. If you want to write your source in ESM define your package as such with "type": "module" and provide a distinct CJS build if you want using exports.

[ljharb]

Nobody should need to use type:module; and we don't need to argue file extensions here - it's just that this PR claims to fix #16580, but doesn't, because fixing it would require eslint.config.mjs to be supported and discovered by default.

[morganney]

You don’t have to define your package as type module. You also don’t have to mix module systems in your package. If you choose to do so then be prepared for custom workarounds. My contention is the associated issue was never really an issue but just a misunderstanding in usage. So the PR should have used Closes instead of Fixes.

[ljharb]

It shouldn't have been closed by this PR either - it was closed as a wontfix. The PR simply has nothing to do with it except maybe "relates to" or "see also".

[morganney]

Well, then this thread can help clarify for posterity.

[mdjermanovic]

How does this fix #16580?

By documenting that in CommonJS projects eslint.config.js must be in CommonJS format, per #16580 (comment).

[ljharb]

@mdjermanovic that would close it if it weren’t already closed, but “fix” doesn’t seem right since the title of the issue is “support .mjs config files”