🚀 Feature: ESM configuration file

[thescientist13]

Is your feature request related to a problem or a nice-to-have?? Please describe.
To continue the journey in supporting ESM in Mocha, it would be nice to have support for ESM based configuration files. Currently this is documented as a known limitation

Configuration file can only be a CommonJS file (.mocharc.js or .mocharc.cjs)

Describe the solution you'd like
Allow ESM based configuration files in projects, either with (.mocharc.js) or without (.mocharc.mjs) a type="module" field in package.json

export default {
  timeout: 30000
}

Describe alternatives you've considered
Only other current alternative in Node is CJS.

Additional context
N / A

[JoshuaKGoldberg]

I'm surprised there wasn't a previous issue filed for this already! 😄

[thescientist13]

Hey @JoshuaKGoldberg , saw you added the label for accepting PRs so was eager to dig into this.

Was looking into the Mocha source and since config lookup and parsing is synchronous, but ESM import is async, was wondering if you had any thoughts / guidance on what might be the best way to tackle this?

As far as I know, the only way to read an ESM file would be through import, e.g.

const config = await import(pathToFileURL(filepath))
  .then(module => module.default));

Or is there another way to parse an ESM file to extract its imports I am not aware of? 🤔

[JoshuaKGoldberg]

I don't have many thoughts / guidance, sorry 😞. We the new maintainer team are still ramping up (#5027). I haven't looked into the implementation details for this or generally loading ESM.

Briefly:

• Other folks have dealt with the async<>sync issue by using synckit. That could work here... but I'd really prefer avoiding workarounds / tech debt if we don't truly need them.
• Changing loadConfig & co. would be a breaking change, but given that many other frameworks are having to do the same thing for ESM, I personally think that's reasonable.

[thescientist13]

Other folks have dealt with the async<>sync issue by using synckit. That could work here... but I'd really prefer avoiding workarounds / tech debt if we don't truly need them.

Yeah, I had seen some similar packages out there but like yourself, was still searching to see if there was a "dependency" free option out there. In particular for synckit, involving in a Worker thread seems like a lot of overhead just read a config file. 🏋️

Changing loadConfig & co. would be a breaking change, but given that many other frameworks are having to do the same thing for ESM, I personally think that's reasonable.

I think this was my next avenue of exploration so good to know there is positive sentiment for that approach. Let me play around with this and will report back if it looks promising.

---

I know this falls more on the side of adding more dependencies, but wasn't sure if you were aware of the tool CosmicConfig, which aims to abstract away the whole config file lookup / parsing ceremony. I haven't personally used it but a number of other big projects use it (like PostCSS I believe) so just figured I would put that out there.

[thescientist13]

Ok, got a repo setup with patch-package (see the patches/ directory) and have a working implementation supporting both .mjs and .js + type="module". Just run npm ci and npm test to see it in action.

Aside from marking a couple functions as async, the main change here is in needing to wrap bin/mocha.js in an async IIFE so that we can run a makeshift "top-level" await (since true top-level await is only available in modules)

Let me know your thoughts.

[JoshuaKGoldberg]

Awesome, thanks for the reference @thescientist13! This will be useful in triaging the feature request. ❤️

aware of the tool CosmicConfig

CosmicConfig is great! It'd be a bigger breaking change to use it in Mocha, but we'd certainly be open to at least an issue being filed to use it. I think we'd want to see a comparison of all the ways Mocha supports config files, all the ways CosmicConfig support config files, and any gaps between. We wouldn't want to lose support for an existing config form if that config form is reasonable & used by users.

[thescientist13]

Thanks for taking a look @JoshuaKGoldberg . 🙏

I'll start on this ESM config PR then following my approach in the demo repo, and can follow up on the CosmicConfig issue after that.

[satyen95]

Hi @thescientist13 I'm also facing the same hassle of handling custom reporters & config files explicitly in .cjs while my whole repo is maintained in module JS by default via package.json type="module". Have you started to add support for this?

@JoshuaKGoldberg Is anyone contributing toward adding support for this?

[JoshuaKGoldberg]

Nobody's sent anything. You'd see it linked here if they did. 🙂

[nbkhope]

Is this issue getting traction? I'm currently migrating my projects to ESM and having a .mocharc.js file with export default triggers the error:

Error: Unable to read/parse [...]\.mocharc.js: Error [ERR_REQUIRE_ESM]: require() of ES Module [...]\.mocharc.js from [...]\node_modules\mocha\lib\cli\config.js not supported.
Instead change the require of .mocharc.js in [...]\node_modules\mocha\lib\cli\config.js to a dynamic import() which is available in all CommonJS modules.

[JoshuaKGoldberg]

Nobody's sent anything. You'd see it linked here if they did. 🙂