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

[natemoo-re]

Feature request

With Node 12.17.x 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.

[afsanefdaa]

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

[029A-h]

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

[andreasg123]

Is the use of next-transpile-modules still the only way to include modules that only provide ESM? I tried switching my project to "type": "module" but I was prompted to rename next.config.js to .cjs. The latter wasn't picked up as a config file, resurfacing an issue with "fs" in another module.

In case it is relevant, my project uses TypeScript. I had to include babel-jest to be able to use Jest.

My final goal is to use next export because the production server doesn't run Node.

[DikoMahendraa]

it worked, I just changed type:module and rename next.config.js to .cjs

[paulshorey]

I ran into a similar issue. If any of the folders inside my Next.js project use {type:"module"}, then next build process can't require() from them. It says "Must use import to load ES Module".

The silly thing is that Webpack/React uses ES Module format (import instead of require). So this is very strange. Next.js server really should use ESM by default, because it's working with an ESM filesystem.

[GitHubFilipe]

Im running into this issue too.
A .js script that I'm importing in my next.config.js, uses "import {...} from '...' directives to call some API functions, thus throwing the error:
SyntaxError: Cannot use import statement outside a module

no matter how I turn it, the combination just doesn't work.

[belgattitude]

For information, ky will move to esm only... next-transpile-modules can be used meanwhile, but esm would be really appreciated.

sindresorhus/ky#322 (comment)

[Janpot]

Created an RFC (#22381) and started an implementation (#22153) for this

[equinusocio]

Just use

const a = import('react-markdown') where ever you want to use the dependency

You can't use import inside next config..

[nedkelly]

I'm having the same issue with react-markdown.
TypeScript
Next.js 11.1.0
Yarn 2
I tried adding esmExternals in next.config.js but still no joy.
Using Dynamic import fixes it though:

const ReactMarkdown = dynamic(() => import('react-markdown'));

@nedkelly are you doing this inside next config?

No, and to be honest, using dynamic import is a little unstable, it sometimes fails to load so it's not really a fix. And it doesn't work in next.config.js.

[alecmev]

No disrespect to the participants, but I think too many people misunderstand this issue, resulting in all sorts of irrelevant ESM problems being reported here. Can commenting be limited to collaborators, please?

[equinusocio]

No disrespect to the participants, but I think too many people misunderstand this issue, resulting in all sorts of irrelevant ESM problems being reported here. Can commenting be limited to collaborators, please?

So we are all stupid. Ok. Anyway the issue is pretty clear, any nextjs plugin which are now modules are totally unusable because nextjs config file doesn't support modules.

[Richienb]

This issue was for allowing the next.config.js to be written with ESM. The most recent conversation is for allowing ESM modules to be loaded within the source code.

The best thing to do is to move this part of the conversation to a seperate issue and guide people who want to talk about that specific thing there.

To people who are having trouble loading modules written in ESM: create a reproduction repository and create a new bug report. As for general discussion about it, we now have #29348.

[equinusocio]

That's totally different from saying "let's close the comments". Anyway, this is the issue i want to follow.

[ctjlewis]

Because Next configs are modules which must be loaded, it will take adding full ESM support to Next to support this for the reasons mentioned in this comment:

#27876 (comment)

Do not add "type": "module" to your package.json (yet)

The esmExternals experimental flag only adds support for ESM externals, i.e., you can import ESM dependencies. You cannot bundle your Next project as an ES module yet.

The same reason that Next cannot load an ESM config (see #9607) is the same reason it cannot load your project if you set "type": "module". If you mark your project as an ES module with "type": "module", Next will break while trying to load next.config.js and compiled JS in .next—these are currently loaded via hard-coded require(...) statements, and trying to require() an ES module throws ERR_REQUIRE_ESM:

next.js/packages/next/server/config.ts

Line 473 in 16a737d

userConfigModule = require(path)

It will actually take upgrading Next core itself to ESM to add full ESM support (as widely requested, e.g. in #9607), which I will explain in detail in a separate issue. It is worth it to undertake that effort, but for now it will suffice to fix the resolution issues below IMO, and let Next back-transpile ESM to CJS for deploy.

I have an experimental branch going to explore this, but Jest ESM support is shoddy and ultimately blocking progress.

[rinarakaki]

@ctjlewis Thank you for sharing your exploration. Based on it, do you think anything else will be straightforward in rewriting CJS to ESM when Jest's ESM support is solved?

---

• Meta: Native support for ES Modules jestjs/jest#9430 to follow the progress of Jest's ESM support.

[ctjlewis]

@rnarkk There are a few obstacles (some related to TS itself, which we may be able to workaround with Node12 resolution as of next release) to getting Next to that point, which I will detail in a separate issue and link here, but the way I'd propose implementing it, you would just need to set "type": "module" or use .mjs extension to signal ESM, and Next would handle the rest (as long as you feed it valid ESM).

For TS projects, you'd want to configure your local project settings to use the new Node12 resolution, so that it forces you to write complete ESM-compatible import specifiers (or use something like tszip to rewrite them for you, which is what I do).

[timneutkens]

I've opened a PR that changes from require() to import() for config loading and adds support for next.config.mjs. I'll keep this issue open as there's still more work to do for "type": "module" in package.json but this change should help until then: #29935

[michaelhays]

FYI, you can now follow along with the "type": "module" progress with this PR: #33637

[michaelhays]

#33637 was just merged into canary 😊

[IGassmann]

Adding it on the newly released version which contains #33637 seem to break Tailwind CSS :/

[ctjlewis]

Adding it on the newly released version which contains #33637 seem to break Tailwind CSS :/

Can confirm, see #34448. I sent in a draft PR at #34451, but it is not ready to merge and it will also take Tailwind adding support for ESM config files before a Next + Tailwind project will actually build as an ES module.

cc @adamwathan

[brianjenkins94]

I still seem to need the hack that goes and writes a package.json file in the .next directory with the contents: { "type": "CommonJS" } using next@canary.

[Maher4Ever]

@ctjlewis Can you please give us an update on any progress regarding ESM support for next.config.js?

[raulfdm]

[raulfdm]

npx next info         

    Operating System:
      Platform: darwin
      Arch: arm64
      Version: Darwin Kernel Version 21.4.0: Fri Mar 18 00:46:32 PDT 2022; root:xnu-8020.101.4~15/RELEASE_ARM64_T6000
    Binaries:
      Node: 16.14.2
      npm: 7.24.2
      Yarn: 1.22.17
      pnpm: 6.27.1
    Relevant packages:
      next: 12.1.6
      react: 18.1.0
      react-dom: 18.1.0

[smitev]

@raulfdm The app starts correctly, but the issue is with the runtime fetching/rendering of the Framer component.
Look at the ./components/FramerElement.tsx how I am trying to do that.

[raulfdm]

@raulfdm The app starts correctly, but the issue is with the runtime fetching/rendering of the Framer component. Look at the ./components/FramerElement.tsx how I am trying to do that.

@smitev I think I misunderstood your problem.

I think the overall problem discussion in this was the ability of having next.config.js with ESM syntax (import/export) and also importing ESM packages inside the config file to be able to configure.

As I said before, it wasn't possible to import any rehype package inside next.config.js just because the config did not support ESM.

Now, your problem is different than that. You want, in runtime, be able to import a ESM package via URL. I don't know anything about this.

I think this is a valid concern and it should be raise in another discussion so vercel team can enhance the existing urlImports feature (which it's experimental yet) to also consider this case.

But again, I don't think it relates to the main concern of this discussion.

[smitev]

I understand. Thanks for the effort @rafipiccolo and @equinusocio.
I will open another discussion for this topic.

[revmischa]

What happened on #29935? Can the next server be upgraded to generate ESM imports and such? Is there a PR somewhere to enable ESM output for NextJS?

[ctjlewis]

Because Next’s dev server is itself CJS, it does not support emitting ESM, nor ”type”: “module” for the same reason.

Rewriting Next itself to be ESM would be a massive undertaking, I’ve tinkered in an experimental branch and it is achievable but would take weeks. But, it’s not anything this team doesn’t know about.

[cseas]

I've been trying to run Next.js with "type": "module" and it works fine with the pages/ directory.
Running into other issues related to tree shaking with app directory.

• app directory throws errors for components that use hooks, so making tree shaking work is essential:
  Tree shaking doesn't work with Typescript barrel files #12557 (comment)
• using deep imports seems to be the only workaround but next build throws an error for ESM libs:
  "next build" doesn't recognise node subpath export patterns in npm packages #46267 (comment)
• which brings us back to this discussion. The error in next build seems to be coming up because Next.js is using CJS.

I haven't seen issues with "type": "module" in the pages/ directory though.
@ctjlewis Would you say using "type": "module" is just a bad idea since Next.js will not emit ESM anyway?

[1aron]

I applied this solution to Master CSS's AOT compiler and it worked fine.

import crossImport from 'cross-import'

const configModule = crossImport('next.config.{js,cjs,mjs,ts}')
const config = configModule.default || configModule

Check out the feature request #44324

[BrownSterring]

sooo? Any news on this?

[RomanSkrypnik]

OMG, this issue since 2019 year...
Comparing to nuxt - next just sucks with its webpack

[karlhorky]

For anyone coming to this (outdated) discussion, there are solutions for ESM in Next.js config already now:

1. next.config.mjs
2. next.config.js with "type": "module" in package.json
3. next.config.ts also has ESM support
   • @devjiwonchoi working on "type": "module" support with next.config.ts` too: fix(next-config-ts): properly handle ESM #68365