Node.js: A brief history of cjs, bundlers, and esm

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"));

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"));

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).

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.

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 .js files as cjs modules unless the package.json sets the “type” property to "module".
• Node.js interprets .cjs files as cjs modules.
• Node.js interprets .mjs files as esm modules.

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.

That’s (almost) all you need to know about cjs and esm modules (as of Dec/2024 🙃). Let me know your thoughts below!