The ESM Plan

[novemberborn]

Here's what we're doing to support ESM in AVA. The work has already been broken up into individual issues that you can work on. See the ESM support project for details.

See https://nodejs.org/docs/latest/api/esm.html for the latest on what Node.js is implementing (this issue was opened when that documentation was for Node.js 13.1.0). I'm expecting this to become available without a flag at some point.

• Firstly, we're moving AVA's Babel support into a separate package that you can install alongside AVA. This will reduce confusion as to what module format AVA supports out of the box. It also allows us to evolve that package independently, which is important since loader hooks may still take some while to land.

• Secondly, we'll be detecting test files with cjs and mjs extensions. Currently, by default, we only look for files with js extensions.

• When loading test files, we'll always load files with cjs extensions using require(). Files with mjs extensions will be loaded using import(). Support loading .mjs test files #2344

• Note that import() itself is currently behind an experimental flag. Allow Node arguments to be configured #2272 will let you configure that flag. We'll print a useful error message if import() is not available and AVA is trying to load an mjs test file.

• When it comes to js files we'll follow the package.json "type" field. So by default we'll treat them as CJS.

• We'll also let you configure how js files (and other files, but not cjs or mjs files) should be loaded. This way you could override the "type" field, or load test files as ESM even if you're publishing CJS. Add configuration to specify how extensions should be loaded #2345

• The Babel provider will detect when you've configured files to be loaded as ESM even though it cannot load them as such, and print an error.

• We'll support ava.config.cjs and ava.config.mjs configuration files. However deciding what to do with ava.config.js files is more difficult. We shouldn't change how it's loaded based on "type" fields, nor can we use the built-in import() since it needs to be enabled. And finally, right now we need to be able to load it synchronously for use with our ESLint plugin. Support ava.config.mjs files #2346

• I'm proposing we remove support for import statements and require() calls from ava.config.js files. In other words, they must only contain export default {} or export default () => ({}) style configurations. This is a breaking change, as at the moment we load ava.config.js using the esm package. However it gives us the best upgrade path.

• We do need to consider what syntax we use in our documentation. I think we should use CJS, until ESM is available without a flag. It's not as hip, but at least it'll work out of the box.

• When loading require modules, if they are loaded from the project itself we can use the above logic to load the files based on their extension. If they're packages and import() is available then that should work. Else, for now, we'll fall back to using require(). Update our handling of the require option to support ESM dependencies #2347

• Dependency tracking for our watch mode also needs work. Make dependency tracking work with ESM imports #2388

[sindresorhus]

We shouldn't change how it's loaded based on "type" fields

Why not?

[novemberborn]

We shouldn't change how it's loaded based on "type" fields

Why not?

First of, Node.js defaults to CJS for js files. Following this default breaks all existing configuration files. With my suggestion to only support export default most simple files will still work.

Changing the "type" field would have the consequence of breaking your AVA configuration, which I'd find surprising.

Finally, if we say you can override how js files are loaded, through configuration, it's confusing that you can't change how the ava.config.js file itself is loaded.

[novemberborn]

I've also just realized our dependency tracking (for the watcher) won't work for ESM. Perhaps we can use the loader plugins, or else we should try and do static analysis. The latter is complicated by new JavaScript & TypeScript syntaxes.

[clitetailor]

IMO, why don't we support Node experimental modules under a flag. For example:

ava --experimental-modules

So that it won't break the current behavior and we can switch to the new modules system when the interoperability and the loader hooks are stable enough.

[novemberborn]

IMO, why don't we support Node experimental modules under a flag. For example:

ava --experimental-modules

So that it won't break the current behavior and we can switch to the new modules system when the interoperability and the loader hooks are stable enough.

#2272 will add a nicer way of defining the Node.js flags applied to the worker processes than what is currently possible. However, ESM is available already without a flag in Node.js 13. We just need to make a bunch of changes to make effective use of it. And yes it would be opt-in, but that's largely due to how the feature is designed in Node.js itself.