RFC: Load next.config.mjs as ESM

[Janpot]

Update: This has shipped! You can now use next.config.mjs.

---

Goals:

• No compilation impact: Loading next config as ESM shouldn't require a babel compilation and shouldn't incur extra startup time.
• Backwards compatible: commonjs should still be supported.

Background:

ECMAScript modules are the official standard format to package JavaScript code for reuse. As the ecosystem moves from commonjs towards ESM, the need for defining Next.js configuration as ESM will rise. Some libraries even started to publish ESM-only modules. Node.js acquired the capability to load ESM from commonjs and Next.js should leverage that to load configuration from config files in ESM format.

• relevant issue: Support ES module format (ESM) in next.config.js #9607

Implementation:

node.js supports loading ESM natively from version 12 on. If next.config.mjs exists in the project root, and the user is on node >=12, Next.js should use dynamic import() to load the default export of next.config.mjs as the Next.js configuration, or next.config.js if the former does not exist. When on node <12 revert to require and next.config.js as is the current behaviour. The choice of mjs extension is in line with the node.js module resolution algorithm.

Since import() is always asynchronous, this will require turning the config loading from a synchronous process into an asynchronous one. In next CLI this shouldn't be too difficult to convert. The challenge will be in custom server that can't boot up before config is loaded. This will probably require moving config loading into the .prepare method.

Out of scope:

Besides enabling ESM support, this will also serve as a basis to build further on:

• support "type": "module" in package.json to enable ESM for .js files
• to load asynchronous configuration
• It will also set the stage for leveraging module loaders to load other formats, e.g. next.config.ts when that node.js feature stabilizes.

Open PR:

#22153

[JacobLey]

Referencing a comment on the PR but I figure this is a better place for discussion:

#22153 (comment)

Potentially we'll have to enable webpack 5 by default for projects using the ESM config file

Why would .mjs be a blocked by Webpack5?

This is just the config file, so it isn't itself transformed by webpack?

I've found Webpack5 is necessary to support native ESM elsewhere in NextJS but that is for transpiler logic.

Also I would argue that #15307 will be resolved by the changes in #22153 because the result of require is now being awaited down the line.
The request there is support to return a top-level promise, not an async function (although returning an async function would be nice as well)

[Janpot]

Why would .mjs be a blocked by Webpack5?

Because the logic in next.js to determine if it needs to enable webpack 4 or 5 requires clearing the module cache, which is possible in commonjs, but not in ESM. So the solution is to never allow webpack 4 when you use ESM, then that logic never has to run.

Keep in mind that this PR is just a pathfinder, commonjs and ESM don't share a common module cache which may be a complete blocker to get it ever released.

[rinarakaki]

Can I ask what the current status of this issue is? Are we still in figuring out the satisfying way to have default ESM support? Please help me understand what is the blocker here.

• Is it backwards compatibility for allowing CommonJS to co-exist?
• Is it because we cannot abandon Webpack 4 yet?
• Is it possible to enable ESM only for those who are using Webpack 5?

[Janpot]

Hi @rnarkk Thanks for your comment. I haven't looked at this in a while, but I'd be happy to fill you in on what I remember were the blockers when I wrote the prototype. My understanding of it may be outdated as for the past few months I haven't been able to follow Next.js core as closely as I used to.

At the time, Next.js did a compatibility check before deciding which webpack version to use. To be able to perform this check it needed to load the config. The config itself may also load webpack (perhaps transitively through plugins), so it's important that when it switches to a different webpack version, the require cache is flushed and the config is loaded again with the correct webpack version. This problem is solvable by only allowing ESM next.config.js when the user has opted in to webpack 5, that way we don't have to do the compatibility check and the config doesn't have to be reloaded with a different webpack version. I don't know yet whether the same conditions still apply in next.js 11.

A second problem that only occurred to me after writing the prototype, and is the reason why I haven't further pursuit it yet, is that commonjs module cache and ESM module cache are completely separated. The implementation of this RFC works by "escaping" the commonjs system and loading next.config.js as ESM natively with node.js. The consequence of this is that any module that is loaded transitively from next.config.js will be cached in the ESM cache, while everything else in next.js core will be cached in the commonjs cache. This means that any shared modules will be instantiated again when loaded through next.config.js. I'm not sure yet how problematic the consequences of this are, but I can imagine some weird bugs coming up from it.

Other than that, the prototype was fully functional for the basic use cases I tested it on at the time of writing, I haven't tried to rebase it yet on latest canary.

IMO, the most stable implementation would be one with a single module cache. Either commonjs, by compiling next.config.js with babel (decided against by core team because of performance implications). Either ESM, by converting next.js core to native node.js ESM (Probably a difficult refactor with lots of blockers).

[Janpot]

closed the PR as next.js seems to be moving to swc which would be much better suited than babel to compile the config without incurring too much overhead

[leerob]

Update: This has shipped! You can now use next.config.mjs.