Next.js: Support ES module format (ESM) in next.config.js

[natemoo-re]

Feature request

With Node 13 landing native support for ES modules, I would expect next.config.js to support ES module format in addition to CJS.

When using type: module in package.json on Node v13.1.0 and an ESM next.config.js format, Next throws an error due to the config resolution logic relying on require.

Describe the solution you'd like

Next should follow Node’s module semantics and allow either CJS or ESM file, depending on user configuration.

Currently, next.config.js uses CJS with require and module.exports. ESM format would allow users to import dependencies and export default the config object.

This theoretically also opens the door to mirror Node’s explicit file extension pattern, which would suggest support for next.config.cjs and next.config.mjs files. This is likely controversial, but it is part of the language.

Describe alternatives you've considered

As statically analyzing the native module format of next.config.js likely introduces a fair amount of complexity, this could be used as an opportunity to introduce "superset" config files (ESM, TypeScript [see #5318, #8044]) which are transpiled to CJS, emitted to the distDir (.next), and read from that location. This would also allow users pinned versions of Node below 13 to benefit from ESM format or strongly typed config files (see @stencil/core for prior art.)

Additional context

The following error is thrown, minimum reproducible files below.

node:97960) Warning: require() of ES modules is not supported.
require() of /PROJECT_NAME/next.config.js from /PROJECT_NAME/node_modules/next/dist/next-server/server/config.js is an ES module file as it is a .js file whose nearest parent package.json contains "type": "module" which defines all .js files in that package scope as ES modules.
Instead rename next.config.js to end in .cjs, change the requiring code to use import(), or remove "type": "module" from /PROJECT_NAME/package.json.
/PROJECT_NAME/next.config.js:1
import path from "path";
^^^^^^

SyntaxError: Cannot use import statement outside a module
    at wrapSafe (internal/modules/cjs/loader.js:983:16)
    at Module._compile (internal/modules/cjs/loader.js:1033:27)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1103:10)
    at Module.load (internal/modules/cjs/loader.js:914:32)
    at Function.Module._load (internal/modules/cjs/loader.js:822:14)
    at Module.require (internal/modules/cjs/loader.js:956:19)
    at require (internal/modules/cjs/helpers.js:74:18)
    at Object.loadConfig [as default] (/PROJECT_NAME/node_modules/next/dist/next-server/server/config.js:105:34)
    at new Server (/PROJECT_NAME/node_modules/next/dist/next-server/server/next-server.js:42:43)
    at new DevServer (/PROJECT_NAME/node_modules/next/dist/server/next-dev-server.js:1:2508)

package.json

{
  "type": "module"
  ...
}

next.config.js

// next.config.js
import withCSS from '@zeit/next-css';
export default withCSS();

[redblue9771]

Node 13 is not yet suitable for production environments, and using the mjs extension is intrusive. Recently I needed a custom server to use better express middleware features, but I have no way to use ESM in any custom server related files. I hope to add an example about using ESM and nodemon when customizing the server.

[natemoo-re]

While I’d love to see ESM support globally in Next, this issue is just about the next.config.js file. Custom servers can support ESM in a similar manner to the custom-server-typescript example.

Let’s not get into a discussion about the merits of .mjs or .cjs. I’m personally not a big fan, but since Node allows both, Next should support them as well.

[afsanefda]

I have the same issue. Do you have any idea how to fix it?

I previously used node 8.10.0 and now changed to 12.16.1 and when I yarn dev it keeps returning me the error in one of my npm packages.

SyntaxError: Cannot use import statement outside a module

I added type:module to package.json but it says:

> Build error occurred
Error [ERR_REQUIRE_ESM]: Must use import to load ES Module: /.../next.config.js
require() of ES modules is not supported.
require() of /..../node_modules/next/dist/next-server/server/config.js is an ES module file as it is a .js file whose nearest parent package.json contains "type": "module" which defines all .js files in that package scope as ES modules.
Instead rename next.config.js to end in .cjs, change the requiring code to use import(), or remove "type": "module" from /.../package.json.

[cooervo]

same here tried to migrate project to use import just to fail on next.config.js

[OctonianCat]

Would love to see this implemented. +1

[hypo-thesis]

This is a bummer. no solution yet ?

[Willi-Smith]

Any progress in implementation of esm syntax so far?

[crshumate]

For anyone running up against this issue. I am using a custom server for complete flexibility in my build.

Node files are located in a top level dir called server and Next files are in a top level dir called src

/root
    - next.config.js
    - package.json - make no changes to this file
    /src
        /pages
    /server
        - package.json
            - this file just needs: {"type":"module"}
        - server.js

As noted in the structure above, place an empty package.json file in a subdir with the node/express/etc files.
In this package.json simply add {"type":"module"}
Ensure all the requires are changed to ES6 import statements and it should build fine.

[sagirk]

As noted in the structure above, place an empty package.json file in a subdir with the node/express/etc files.
In this package.json simply add {"type":"module"}
Ensure all the requires are changed to ES6 import statements and it should build fine.

Nice! 👍

If you want to retain server.js in the root, though, simply rename it from server.js to server.mjs for the time being. Works without requiring a type entry in package.json.

[Rowno]

Since Node.js 12.17.0 ES modules have been enabled by default (a flag is no longer required). So ES modules are now available in an LTS version of Node.js:
https://nodejs.org/en/blog/release/v12.17.0/

Also it looks like you can use normal .js file extensions if you add "type": "module" to your package.json:
https://nodejs.org/docs/latest-v12.x/api/esm.html#esm_package_json_type_field