Skip to content
Tutorials Center
My learning

Topics

JavaScript Reference ยท Classes and Modules

CommonJS versus ES modules

Compare CommonJS (require, module.exports) with ES modules (import, export): loading, live bindings, this, top-level await, interop and when to use each.

JavaScript has two module systems. CommonJS (CJS) was created for Node.js before the language had modules: you call require() to load a file and assign to module.exports to share values. ES modules (ESM) are the standard built into the language: you write import and export, and browsers, Node.js and other runtimes all understand them.

New code should use ES modules. You still meet CommonJS in older Node.js packages, config files and tooling, so you need to read both.

JavaScript
// CommonJS
const path = require("node:path");
module.exports = { join: path.join };

// ES modules
import path from "node:path";
export const join = path.join;

Try it

JS CommonJS needs wiring; ESM is built in

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS Differences you can observe

Press Run (or Ctrl + Enter) to see the console output here.

No output.

How they differ

Syntax and loading

CommonJS loads synchronously and at run time: require("./a") runs a.js right there and returns its module.exports. Because require() is an ordinary function call, it can sit inside an if or take a computed string.

ES modules are static. import and export declarations must be at the top level and use string literals, so tools can read the dependency graph without running anything. That enables tree shaking (dropping unused exports) and early errors for a misspelled export. Loading is asynchronous. When you need run-time loading, use dynamic import().

Values versus live bindings

A CommonJS export is whatever object you assign to module.exports. If you export a number, importers receive that number as it was at that moment. An ES export is a live binding: importers see the current value of the exporting module's variable, as the first example shows. Importers cannot assign to an imported binding.

Strict mode, this and top-level await

ES modules are always in strict mode, and module top-level this is undefined. In CommonJS, code is sloppy by default and top-level this equals module.exports. Only ES modules support top-level await.

Variables that do not exist in ESM

require, module, exports, __filename and __dirname are CommonJS wrapper variables. In an ES module, use import.meta (for example import.meta.url) instead.

Using them together in Node.js

Node.js decides the system by file extension (.mjs is ESM, .cjs is CommonJS) or by the nearest package.json "type" field for .js files. ES modules can import CommonJS packages, and the exported value arrives as the default import. CommonJS can load an ES module only with dynamic import(), which returns a promise, though recent Node.js versions also allow require() of synchronous ES modules. Check your version's documentation.

Usage notes

  • Pick ESM for new code, in browsers and in Node.js alike. Browsers only run ES modules (<script type="module">).
  • Do not mix styles in one file. A file with import or export is a module; require is not defined there.
  • Circular dependencies work in both systems, but a partially filled export can surprise you: CommonJS may return an incomplete module.exports; ESM may hit an uninitialized let, const or class binding.
  • Default and named exports map awkwardly to module.exports = fn. When importing such a package, the whole value is the default import.
  • Bundlers and TypeScript let you write ESM and still produce CommonJS output for older targets.

Browser support

ES modules are supported by every current browser and by Node.js. CommonJS is not part of the web platform: it works only in Node.js and in bundlers that emulate it.