Introduction
If you're a Node.js developer, you've probably heard of cjs and esm modules but may be unsure why there's two and how do these coexist in Node.js applications. This blogpost will briefly walk you through the history of JavaScript modules in Node.js (with examples 🙂) so you can feel more confident when dealing with these concepts.
The global scope
Initially JavaScript only had a global scope were all members were declared. This was problematic when sharing code because two independent files may use the same name for a member. For example:
greet-1.js
function greet(name) {
return `Hello ${name}!`;
}
greet-2.js
var greet = "...";
index.html
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Collision example</title>
</head>
<body>
<!-- After this script, `greet` is a function -->
<script src="greet-1.js"></script>
<!-- After this script, `greet` is a string -->
<script src="greet-2.js"></script>
<script>
// TypeError: "greet" is not a function
greet();
</script>
</body>
</html>
CommonJS modules
Node.js formally introduced the concept of JavaScript modules with CommonJS (also known as cjs). This solved the collision problem of shared global scopes since developers could decide what to export (via module.exports) and import (via require()). For example:
src/greet.js
// this remains "private"
const GREETING_PREFIX = "Hello";
// this will be exported
function greet(name) {
return `${GREETING_PREFIX} ${name}!`;
}
// `exports` is a shortcut to `module.exports`
exports.greet = greet;
src/main.js
// notice the `.js` suffix is missing
const { greet } = require("./greet");
// logs: Hello Alice!
console.log(greet("Alice"));
npm packages
Node.js development exploded in popularity thanks to npm packages which allowed developers to publish and consume re-usable JavaScript code. npm packages get installed in a node_modules folder by default. The package.json file present in all npm packages is especially important because it can indicate Node.js which file is the entry point via the "main" property. For example:
node_modules/greeter/package.json
{
"name": "greeter",
"main": "./entry-point.js"
// ...
}
node_modules/greeter/entry-point.js
module.exports = {
greet(name) {
return `Hello ${name}!`;
}
};
src/main.js
// notice there's no relative path (e.g. `./`)
const { greet } = require("greeter");
// logs: Hello Bob!
console.log(greet("Bob"));
Bundlers
npm packages dramatically sped up the productivity of developers by being able to leverage other developers' work. However, it had a major disadvantage: cjs was not compatible with web browsers. To solve this problem, the concept of bundlers was born. browserify was the first bundler which essentially worked by traversing an entry point and "bundling" all the require()-ed code into a single .js file compatible with web browsers. As time went on, other bundlers with additional features and differentiators were introduced. Most notably webpack, parcel, rollup, esbuild and vite (in chronological order).
ECMAScript modules
As Node.js and cjs modules became mainstream, the ECMAScript specification maintainers decided to include the module concept. This is why native JavaScript modules are also known as ESModules or esm (short for ECMAScript modules).
esm defines new keywords and syntax for exporting and importing members as well as introduces new concepts like default export. Over time, esm modules gained new capabilities like dynamic import() and top-level await. For example:
src/greet.js
// this remains "private"
const GREETING_PREFIX = "Hello";
// this will be exported
export function greet(name) {
return `${GREETING_PREFIX} ${name}!`;
}
src/part.js
// default export: new concept
export default function part(name) {
return `Goodbye ${name}!`;
}
src/main.js
// notice the `.js` suffix is required
import part from "./part.js";
// dynamic import: new capability
// top-level await: new capability
const { greet } = await import("./greet.js");
// logs: Hello Alice!
console.log(greet("Alice"));
// logs: Bye Bob!
console.log(part("Bob"));
Over time, esm became widely adopted by developers thanks to bundlers and languages like TypeScript since they are capable of transforming esm syntax into cjs.
Node.js cjs/esm interoperability
Due to growing demand, Node.js officially added support for esm in version 12.x. Backwards compatibility with cjs was achieved as follows:
- Node.js interprets
.jsfiles ascjsmodules unless thepackage.jsonsets the "type" property to"module". - Node.js interprets
.cjsfiles ascjsmodules. - Node.js interprets
.mjsfiles asesmmodules.
When it comes to npm package compatibility, esm modules can import npm packages with cjs and esm entry points. However, the opposite comes with some caveats. Take the following example:
node_modules/cjs/package.json
{
"name": "cjs",
"main": "./entry.js"
}
node_modules/cjs/entry.js
module.exports = {
value: "cjs"
};
node_modules/esm/package.json
{
"name": "esm",
"type": "module",
"main": "./entry.js"
}
node_modules/esm/entry.js
export default {
value: "esm"
};
The following runs just fine:
src/main.mjs
import cjs from "cjs";
import esm from "esm";
// logs: { value: 'cjs' }
console.log(cjs);
// logs: { value: 'esm' }
console.log(esm);
However, the following fails to run:
src/main.cjs
// OK
const cjs = require("cjs");
// Error [ERR_REQUIRE_ESM]:
// require() of ES Module (...)/node_modules/esm/entry.js
// from (...)/src/main.cjs not supported
const esm = require("esm");
console.log(cjs);
console.log(esm);
The reason why this is not allowed is because esm modules allow top-level await whereas the require() function is synchronous. The code could be re-written to use dynamic import(), but since it returns a Promise it forces to have something like the following:
src/main.cjs
(async () => {
const { default: cjs } = await import("cjs");
const { default: esm } = await import("esm");
// logs: { value: 'cjs' }
console.log(cjs);
// logs: { value: 'esm' }
console.log(esm);
})();
To mitigate this compatibility problem, some npm packages expose both cjs and mjs entry points by leveraging package.json's "exports" property with conditional exports. For example:
node_modules/esm/entry.cjs:
// usually this would be auto-generated by a tool
module.exports = {
value: "esm"
};
node_modules/esm/package.json:
{
"name": "esm",
"type": "module",
"main": "./entry.cjs",
"exports": {
"import": "./entry.js",
"require": "./entry.cjs"
}
}
Notice how "main" points to the cjs version for backwards compatibility with Node.js versions that do not support the "exports" property.
Conclusion
That's (almost) all you need to know about cjs and esm modules (as of Dec/2024 🙃). Let me know your thoughts below!
Top comments (1)
Thankyou so much enjoy your video very good with helping me understand you are so clever, my self find it hard because of the letter writing more with colour code I have dyslexia.