JavaScript has two module systems: CommonJS (Node.js, synchronous, dynamic) and ES Modules (the standard, static, async). They're not fully interoperable. Understanding why affects how you publish libraries, configure bundlers, and debug `require is not defined` or `ERR_REQUIRE_ESM` errors.
CommonJS was created for Node.js (2009) before there was a standard module system. It's synchronous, dynamic, and built into Node.js without any config.
// math.js, CJS exportconst add = (a, b) => a + b;const PI = 3.14159;module.exports = { add, PI };// or individually:module.exports.add = add;// Or using the shorthand:exports.multiply
Curated Video Reference
YouTube
Hand-picked video lecture to deepen your understanding of Module Systems (ESM vs CommonJS)
ES Modules are the JavaScript standard (ES2015 / ES6), now supported natively in all modern browsers and Node.js 12+.
// math.js, ESM exportexport const add = (a, b) => a + b;export const PI = 3.14159;export default function multiply(a, b) { return a * b; }
// app.js, ESM importimport { add, PI } from './math.js'; // named importsimport multiply from './math.js'; // default importimport * as math from './math.js'; // namespace import// Dynamic import, returns a Promiseconst { add } = await import('./math.js');
ESM characteristics:
import / export are parsed statically at parse time (not runtime)
Imports are live read-only bindings to the exported value, not copies
import statements are hoisted; module evaluation is async
Circular dependencies are handled differently (live bindings vs cached exports)
Files must have .mjs extension or "type": "module" in package.json for Node.js to treat them as ESM
In browsers: <script type="module"> enables native ESM
ESM's static structure enables tools to know the full import graph at build time, before any code runs. This is what makes tree shaking possible. With CJS:
// CJS, impossible to statically analyseconst moduleName = condition ? 'lib-a' : 'lib-b';const lib = require(moduleName); // which exports are used? unknown at build time
With ESM, all imports are at the top level and can't be conditional:
// ESM, static, analysableimport { specificExport } from './lib.js'; // bundler knows exactly what's used
Nearest package.json's "type" field: "type": "module" = all .js files are ESM; "type": "commonjs" (default) = all .js files are CJS
# This fails if the file uses ESM and type isn't set:node app.js # Error: Cannot use import statement in a module# Fix options:# 1. Rename to app.mjs# 2. Add "type": "module" to package.json# 3. Use dynamic import() from CJS: const mod = await import('./esm-module.mjs')
ESM can import CJS: works, but you only get the default export (the whole module.exports object). Named exports from CJS files don't exist in ESM, the entire export is the default:
// cjs-lib.jsmodule.exports = { foo: 1, bar: 2 };// esm-consumer.mjsimport cjsLib from './cjs-lib.js';console.log(cjsLib.foo); // 1, works, but not named importsimport { foo } from './cjs-lib.js'; // May work in bundlers (they analyze CJS), not in Node.js
CJS cannot require() ESM: this is the ERR_REQUIRE_ESM error. CJS require() is synchronous; ESM evaluation is async. They're fundamentally incompatible.
// This throws ERR_REQUIRE_ESM:const esmLib = require('./esm-lib.mjs');// Fix: use dynamic import(), works in CJS (it returns a Promise)const esmLib = await import('./esm-lib.mjs');
Node.js enforces one module system per file. import in a .js file without "type": "module" throws a SyntaxError. require in an .mjs file throws ReferenceError.
Node.js (and native browser ESM) require full file extensions. Bundlers are lenient and resolve ./utils โ ./utils.ts. But native Node.js ESM: import './utils' fails; import './utils.js' works.
3. Using module.exports = ... then expecting named imports to work in ESM#
// CJS: module.exports = { a, b }// ESM consumer (in a bundler):import { a, b } from './lib.cjs'; // bundlers handle this// In Node.js native ESM:import lib from './lib.cjs'; // only default import worksconst { a, b } = lib; // destructure manually
4. Not setting the exports field in a library's package.json#
Without exports, Node.js resolves to main (CJS). Bundlers look at module (ESM). Without exports, deep imports (import { something } from 'mylib/utils') may break because you haven't explicitly allowed them.