error [err_require_esm]: require() of es module

Node.js is a popular JavaScript runtime built on Chrome’s V8 JavaScript engine, used widely for developing backend applications. As JavaScript continues to evolve, so does the way Node.js handles different module types. One such transition is the shift from the CommonJS module system (require()) to the ES Modules system (import/export).

For developers working with Node.js, one frustrating error they might encounter during this transition is the error [err_require_esm]: require() of es module. This error can cause confusion, particularly for developers who are unfamiliar with ES Modules and the nuances of working with them in Node.js.

In this article, we’ll break down the root causes of this error, how to fix it, and offer best practices for using ES Modules in Node.js applications. We’ll also explain the difference between CommonJS and ES Modules, and explore how developers can navigate these changes effectively.

1. What Is the [ERR_REQUIRE_ESM] Error?

The error [err_require_esm]: require() of es module typically occurs in Node.js when you attempt to use the require() function to import an ES module (a module that uses import and export syntax) in a context where it’s not allowed. ES Modules are a newer JavaScript module system introduced to provide better support for static analysis, tree shaking, and other modern JavaScript features.

In older versions of Node.js (and JavaScript), CommonJS modules were the default. CommonJS uses require() to import dependencies, which is synchronous and works well for server-side environments. However, ES Modules bring an asynchronous approach to module loading, making them more suited for modern JavaScript environments.

Node.js, starting with version 12, started supporting ES Modules natively, but this support is different from CommonJS in several important ways, leading to the error [err_require_esm]: require() of es module error when developers mistakenly try to use CommonJS-style imports for ES Modules.

2. The Evolution of Modules in JavaScript

CommonJS Modules

CommonJS (CJS) is the traditional module system used in Node.js. It’s synchronous and typically works well in server-side applications where modules are loaded locally from the filesystem. CommonJS modules use require() to import dependencies and module.exports to export functionalities. Here’s a simple example:

ES Modules (ESM)

ES Modules (ESM), on the other hand, is the modern JavaScript module syntax, officially introduced in ECMAScript 6 (ES6). ES Modules use the import and export keywords and offer several advantages over error [err_require_esm]: require() of es module, such as better optimization for tree shaking, support for dynamic imports, and asynchronous loading of modules.

Here’s an example of an ES Module:

3. Root Causes of the error [err_require_esm]: require() of es module

The error [err_require_esm]: require() of es module happens when Node.js encounters a module that is being loaded using require() but is designed to work with ES Modules. Below are some common reasons why this error might occur:

Incorrect Import Statements

The error [err_require_esm]: require() of es module typically occurs when developers mix require() (used in CommonJS) with import/export (used in ES Modules). ES Modules cannot be loaded using require() directly. Attempting to do so causes Node.js to throw the error [err_require_esm]: require() of es module.

Example:

Mismatched Module Types

If your project has a mix of ES Modules and CommonJS modules, you might run into this error [err_require_esm]: require() of es module if you try to load an ES Module using require(). Node.js expects you to use import statements when working with ES Modules, and vice versa.

Node.js Configuration Issues

Node.js distinguishes between CommonJS and ES Modules based on the project’s configuration. If your project’s package.json doesn’t specify that you’re using ES Modules, Node will attempt to load .js files using the CommonJS syntax, even if those files are written in ES Module format.

4. How to Fix the error [err_require_esm]: require() of es module

Now that we understand the causes of the error [err_require_esm]: require() of es module, let’s explore how to fix it in various scenarios.

Solution 1: Use import Instead of require()

Since ES Modules are intended to be used with the import/export syntax, you should replace all require() statements with import. For example:

Ensure all your .js or .mjs files that use ES Modules are imported using import statements, not require().

Solution 2: Configure type: "module" in package.json

If your project is using ES Modules and you want Node.js to treat .js files as ES Modules, you need to configure the type field in your package.json file.

This configuration tells Node.js to treat .js files as ES Modules, which will allow you to use import and export instead of require() and module.exports.

Solution 3: Use .mjs Extension

If you don’t want to modify the package.json, you can also use the .mjs extension for files that are ES Modules. This will allow Node.js to correctly interpret them as ES Modules, regardless of the type field in package.json.

Solution 4: Use --experimental-modules Flag (Older Node Versions)

If you’re using an older version of Node.js that doesn’t fully support ES Modules, you can enable experimental support for ES Modules using the --experimental-modules flag when running your Node.js application.

5. Best Practices for Working with ES Modules in Node.js

When transitioning to ES Modules, it’s essential to follow some best practices to ensure compatibility and ease of maintenance:

Migrating from CommonJS to ES Modules

• Consistency: Stick with one module system throughout your project. Mixing CommonJS and ES Modules can lead to confusion and errors.
• Dependencies: Check if your dependencies support ES Modules, as some older packages may still rely on CommonJS.
• Refactoring: Consider refactoring your codebase gradually. Start by migrating smaller parts of your application to ES Modules.

Use import/export Consistently

If your project uses ES Modules, ensure all files use the import/export syntax. Mixing require() and import in the same project can lead to errors.

Keep Dependencies Up-to-date

Many older packages may not yet support ES Modules. Regularly check for updates or alternatives that support modern JavaScript features.

6. Frequently Asked Questions (FAQs)

Q1: Can I use require() with ES Modules? No, require() is for CommonJS modules, while ES Modules must be imported using import.

Q2: What if my project uses both ES Modules and CommonJS? You can have both in the same project, but ensure you follow the appropriate syntax for each. Use import/export for ES Modules and require() for CommonJS.

Q3: What if my dependencies don’t support ES Modules? Consider using CommonJS for the time being or look for updated versions of your dependencies.

7. Conclusion

The error [err_require_esm]: require() of es module is a common issue that arises when developers mix CommonJS and ES Modules in Node.js. Understanding the difference between these two module systems, along with the proper configuration of your project.