Next.js ERR_REQUIRE_ESM

Shivan M.

—February 15, 2024

The Problem

Installing and importing third-party packages into your Next.js application can create troublesome errors. Usually, these errors are the result of version mismatches and incorrect import statements.

In particular, the following error relates to the use of ESM (ECMAScript modules), which are a modern format for JavaScript modules:

Error [ERR_REQUIRE_ESM]: Must use import to load ES Module

ES modules make use of the import statement instead of the require statement. You may run into this issue when trying to use the require statement to add a package to your application that is an ES module.

The Solution

Migration to ESM

When importing third-party packages, a new release could convert the package into an ESM-only package. In this case, the package can no longer be imported using require() and instead you have to use a dynamic import.

Suppose you have a library called bar that was previously a CJS (CommonJS) module, imported as follows:

const bar = require("bar");

If this package has migrated to be an ESM-only package, you now need to import it like so:

import bar from "bar";

Downgrade Packages

If the ERR_REQUIRE_ESM error is not occurring in your codebase, but rather in one of your dependencies, it could be that you have changed the version of a transitive dependency without realizing it.

In the code below, we require a package called bar, which depends on a package called foo. We also depend on foo in our codebase, but we haven’t explicitly used the require statement.

const bar = require("bar")

In node_modules/bar/index.js:

const foo = require ("foo")

If we change the version of foo in our package.json to a version where it is now ESM-only, we will see that bar will throw an error when imported. This is because bar depended on the CJS implementation of foo which it can no longer import.

To fix this, we can do one of two things:

• Change the package version of bar to one that migrates from the CJS version of foo to the ESM version.
• Downgrade our foo package back to the latest CJS version.

In general, if you encounter this error and are unable to identify a root cause, a good start is to downgrade the latest updated packages to their previous versions.

Importing an ES Module From a CommonJS Module

When importing an ES module into a CJS module in TypeScript, the import statement is transpiled into a require statement. This will cause the error in question.

In this scenario, to make our code work, we have to modify our TypeScript configuration.

The first step is to set our module option configuration to es2020 and then to set esModuleInterop to true in tsconfig.json.

We need to set the module option to es2020 because if it is set to CommonJS, then the import statement will be transpiled to require.

With this configuration, we can import ES modules, and require CJS modules, as needed.

const cjsModule = require("bar");
import foo from "foo";

Further Reading

• Node.js ECMAScript modules