Fixing Next.js Error: Import ES module ERR_REQUIRE_ESM

If you are developing with Next.js and encounter the Next.js Error: Import ES module ERR_REQUIRE_ESM, this error is typically related to an incompatibility between ECMAScript modules (ESM) and CommonJS (CJS) module systems. Next.js, from version 13 and onwards, has been heavily leaning towards ESM support, which means that issues can occur if your project, or any dependencies, are utilizing the older CommonJS syntax or patterns. Let’s dive into understanding the problem and how to resolve it.

Understanding the Error

This error generally occurs when you, or a package you are using, attempt to ‘require’ an ES module. In Modern JavaScript development, there are mainly two types of module systems: the new ECMAScript modules (ESM) which use import/export, and the traditional Node.js CommonJS modules (CJS) that utilize require/module.exports. When ESM-compatible files are imported using CJS’ require() syntax, Node.js will throw the ERR_REQUIRE_ESM error. This becomes further complicated as Next.js enhances its ESM support, encouraging developers to migrate away from CJS patterns.

Solving the Error

The solution to this problem usually involves updating your import statements and ensuring that your environment is set up to support ESM. Begin by identifying which modules are causing the error. This can be done through the stack trace that accompanies the error message, it will typically point to a specific file or dependency that is incorrectly imported. Once identified, you’ll need to update the import style from the CommonJS approach to the ES module syntax.

For instance, if you have a file that looks like:

const packageName = require('esm-package')

You’d need to update it to use the ES module syntax:

import packageName from 'esm-package';

However, in some cases, especially when dealing with external dependencies, one cannot simply change the require statement to an import. If the package in question does not support ESM, you can either:

1. Find an alternative package that is ESM compatible.
2. Downgrade to a version of the package that did not employ ESM if available.
3. Use dynamic imports within an async function, as they are more forgiving when mixing ESM and CJS patterns.

A dynamic import using an async/await pattern may look like this:

async function loadPackage() {
  const packageName = await import('esm-package');
  // Use 'packageName' here
}

With proper syntax integration, you should no longer receive the ERR_REQUIRE_ESM error. Keep in mind to analyze each instance and apply the most fitting solution.

Another strategy is to ensure that the entire project fully embraces the ES module by configuring your development environment, including the package.json, appropriately:

{
    "type": "module"
}

Adding the type": "module" instruction to your package.json will signal to Node.js that .js files should be treated as ES modules.

Working Example

Let’s assume we are attempting to use an ES module package correctly within a Next.js server component:

// pages/_middleware.js

import packageName from 'esm-package';

// Middleware logic using the packageName

This should provide a conflict-free integration of an ES module within a Next.js environment. Check the package documentation for any specifics about importing it as an ES module.

If you need to use conditional importing or are handling a dependency that doesn’t always need to be loaded, you could potentially use dynamic imports:

// pages/_middleware.js

async function handler(req, res) {
    if (condition) {
        const packageName = await import('esm-package');
        // Leverage packageName in your middleware logic
    }
}

This asynchronous pattern allows you to leverage ES modules even in situations where static import statements might not be suitable, thus overcoming the ERR_REQUIRE_ESM error.