CommonJS and ESM modules interoperability in NodeJS
![Cover Image for CommonJS and ESM modules interoperability in NodeJS](/_next/image?url=https%3A%2F%2Fcdn.sanity.io%2Fimages%2Fzrogyf5w%2Fproduction%2F42a29ce9a758792785c4554e2d23cf7d598677bb-5477x3651.jpg%3Frect%3D0%2C457%2C5477%2C2739%26w%3D2000%26h%3D1000%26fit%3Dmax%26auto%3Dformat&w=3840&q=75&dpl=dpl_8E5cV1AN43dCT29N31egbi7pk5HP)
![Author's Profile Pic](/_next/image?url=https%3A%2F%2Fcdn.sanity.io%2Fimages%2Fzrogyf5w%2Fproduction%2Fae3f51e57c3e9f92a8a4e4255c51cee669326d62-800x800.jpg%3Fw%3D64%26h%3D64%26fit%3Dcrop%26auto%3Dformat&w=128&q=75&dpl=dpl_8E5cV1AN43dCT29N31egbi7pk5HP)
Introduction
NodeJS supports two types of module systems, CommonJS, and ESM (also known as ECMAScript modules or ES6 modules). You might have come across these terms around the internet and also due to errors being thrown at your face like the following.
Uncaught SyntaxError: Cannot use import statement outside a module
ReferenceError: require is not defined
Error [ERR_REQUIRE_ESM]: require() of ES Module not supported
NodeJS only supported CommonJS modules in the early days, then from around v8.x
NodeJS started experimental support for ESM and things began to become a bit complex.
Given these two types of modules, interoperability came into question.
Let's look at how to resolve these kinds of errors and work out the kinks of using ESM and CommonJS together.
Importing CommonJS in ESM
ECMAScript modules are the official standard format to package JavaScript code for reuse.
You don't need to worry about which type of module you are importing when using ESM. Because ESM supports importing CommonJS modules using an import
statement.
Let's create two files, one for CommonJS and another for ESM.
// cjs.cjs
const name = "Darth Vader";
const ability = () => {
return "Can drive spaceship";
};
module.exports = { name, ability };
// esm.mjs
const name = "Messi";
const ability = () => {
return "Can kick balls";
};
export default { name, ability };
export const extra = "He won the world cup";
Notice that we are using .cjs
and .mjs
extensions for the respective modules.
If the type
property in package.json
is omitted or set to commonjs
we can use .js
instead of .cjs
and use .mjs
for the files we want to behave as ESM.
If the type
property in package.json
is set to module
we can use .js
instead of .mjs
and use .cjs
for the files we want to behave as CommonJS.
// esm-consumer.mjs
// importing esm in esm
import messi from "./esm.mjs";
console.log(messi.name, messi.ability());
// importing cjs in esm
import darthVader from "./cjs.cjs";
console.log(darthVader.name, darthVader.ability());
As you can see in the example above, we can import the CommonJS modules using the import
statement just like if we had imported an ESM module.
We can also destructure the imported object from CommonJS just like we destructure an import from ESM.
// importing cjs in esm
import { name, ability } from "./cjs.cjs";
Importing ESM in CommonJS
CommonJS doesn't support importing ESM modules with require
statements. This is because ES modules have asynchronous execution.
Instead, we can use dynamic import()
statements to import ESM in CommonJS. Also, note that the import()
statement is not only limited to being used in CommonJS modules, it can be used in ESM modules too.
This import()
call is not the same as the import
statement in ESM modules, only the spelling is identical.
import()
returns a promise and the default
and named exports can be accessed by destructuring the resolved value of the promise.
// importing cjs in cjs
const darthVader = require("./cjs.cjs");
console.log(darthVader.name, darthVader.ability());
// importing esm in cjs
import("./esm.mjs").then(({ default: messi, extra }) => {
console.log(messi.name, messi.ability(), extra);
});
You might get errors while importing libraries like lodash-es
in your CommonJS files because those libraries export an ESM module. Use dynamic import()
calls for these libraries instead of require()
to fix those errors.
Conclusion
I hope this article helped you in making sense of the two module systems in NodeJS and their interoperability. Thanks for reading!