Modules: ESM and CommonJS

Two module systems

Node.js supports two module systems that cannot be freely mixed:

Feature	ESM	CommonJS
Syntax	`import` / `export`	`require()` / `module.exports`
File extension	`.mjs` or `.js` with `"type":"module"`	`.cjs` or `.js` without `"type":"module"`
Loading	Static, analysed at parse time	Dynamic, executed at runtime
Top-level `await`	Supported	Not supported
Default in Node 24+	Yes, with `"type": "module"` — and CJS can `require()` it	Legacy default

CommonJS (CJS)

CommonJS was the original Node.js module system. It is still widely used in older packages and tooling.

// @skip-verify multi-file: illustrative
// math.js (CommonJS)
function add(a, b) { return a + b; }
function multiply(a, b) { return a * b; }

module.exports = { add, multiply };      // named exports via object
// OR: module.exports = add;             // single default export

// main.js (CommonJS)
const { add, multiply } = require('./math');
console.log(add(2, 3));       // 5
console.log(multiply(4, 5));  // 20

require() is synchronous and loads the file immediately when the line is executed. This means you can require() inside an if block or a function.

ECMAScript Modules (ESM)

ESM is the official JavaScript module standard. It is now the recommended system for new Node.js projects.

// @skip-verify multi-file: illustrative
// math.mjs (ESM — named exports)
export function add(a, b) { return a + b; }
export function multiply(a, b) { return a * b; }

// utils.mjs (ESM — default export)
export default function formatNumber(n) {
  return n.toFixed(2);
}

// main.mjs (ESM — named import)
import { add, multiply } from './math.mjs';
import formatNumber from './utils.mjs';

console.log(add(2, 3));            // 5
console.log(formatNumber(3.14159)); // '3.14'

import statements are static — they must appear at the top of the file and are resolved before any code runs. This enables tree-shaking (dead-code elimination) by bundlers.

Enabling ESM in Node.js

Two ways to tell Node.js a file uses ESM:

"type": "module" in package.json — all .js files in that package are treated as ESM. Use .cjs for any file that must stay CommonJS.
.mjs file extension — always treated as ESM regardless of package.json.

{
  "name": "my-app",
  "type": "module"
}

Named vs default exports

// @skip-verify multi-file: illustrative
// Named: export multiple bindings, import with exact names (or rename)
export const PI = 3.14159;
export function area(r) { return PI * r * r; }

import { PI, area } from './circle.mjs';
import { area as circleArea } from './circle.mjs'; // rename

// Default: one main export per file, imported with any name
export default class Logger { /* ... */ }

import Logger from './logger.mjs';
import MyLogger from './logger.mjs'; // same thing, different local name

Runnable ESM demo

This snippet runs in the Node.js runtime (module resolution requires Node). It demonstrates how an ES module with named exports works end-to-end using inline dynamic import().

// ESM inline via data: URL — requires Node runtime
const src = `
  export function add(a, b) { return a + b; }
  export const VERSION = '1.0.0';
`;
const mod = await import('data:text/javascript,' + encodeURIComponent(src));
console.log('add(3, 4):', mod.add(3, 4));
console.log('VERSION:', mod.VERSION);

Node.js

// Dynamic import of an inline ESM module via data: URL
const src = [
  'export function add(a, b) { return a + b; }',
  'export const VERSION = "1.0.0";',
].join('\n');

import('data:text/javascript,' + encodeURIComponent(src)).then(function(mod) {
  console.log('add(3, 4):', mod.add(3, 4));
  console.log('VERSION:', mod.VERSION);
  console.log('module keys:', Object.keys(mod).filter(function(k) { return k !== 'default'; }).join(', '));
});

Needs the Node.js runtime — open in StackBlitz to run.

CJS/ESM interop cheat sheet

Real Node.js codebases mix old CommonJS packages with new ESM code constantly, so the interop rules matter even in an “all-ESM” project the moment it depends on an older package. The full detail — including the module resolution algorithm and the exports map — lives in Module Resolution; this is the cheat sheet for what you will actually trip over while writing application code.

Question	Answer on Node 24
Can CJS `require()` an ESM file?	Yes, by default — unless the ESM file uses top-level `await`, which throws `ERR_REQUIRE_ASYNC_MODULE`
Does `__dirname` exist in an ESM file?	No — referencing it throws `ReferenceError`. Use `import.meta.dirname` instead
Do `import` bindings update when the source module reassigns them?	Yes — ESM imports are live bindings, not copies
Do `require()`-destructured values update the same way?	No — CJS gives you a snapshot of the value at the moment `require()` ran
What does `import x from './cjs-file.cjs'` see when `module.exports = someValue`?	`someValue`, as the default export
Does a plain `.js` file need `"type": "module"` to use `import`/`export`?	On Node 24, Node can auto-detect ESM syntax and run the file as a module even without the field (`detect-module`) — but an explicit `"type"` is still the clearer, faster-resolving choice

flowchart TD
  A["require('./file.mjs')"] --> B{"Does file.mjs use top-level await?"}
  B -->|"no"| C["Works — module.exports-style access to the ESM's exports"]
  B -->|"yes"| D["Throws ERR_REQUIRE_ASYNC_MODULE"]
  D --> E["Fix: use dynamic import('./file.mjs') instead, awaited inside an async function"]

require() of an ESM file works unless the file has a top-level await

Node.js

const fs = require('node:fs');
const path = require('node:path');

const syncEsmPath = path.join(__dirname, 'sync-sibling.mjs');
const asyncEsmPath = path.join(__dirname, 'async-sibling.mjs');
fs.writeFileSync(syncEsmPath, "export function add(a, b) { return a + b; }\nexport const VERSION = '1.0.0';\n");
fs.writeFileSync(asyncEsmPath, "await new Promise((r) => setTimeout(r, 0));\nexport const value = 42;\n");

try {
  // require() of a synchronous ESM file works by default on Node 24
  const esm = require(syncEsmPath);
  console.log('require(sync esm).add(2,3):', esm.add(2, 3));

  // require() of an ESM file with top-level await cannot work synchronously
  try {
    require(asyncEsmPath);
  } catch (e) {
    console.log('require(async esm) threw:', e.code);
  }
} finally {
  fs.unlinkSync(syncEsmPath);
  fs.unlinkSync(asyncEsmPath);
}

Output (verified on Node 24)

require(sync esm).add(2,3): 5
require(async esm) threw: ERR_REQUIRE_ASYNC_MODULE

The next demo writes one .mjs sibling and two .cjs siblings to show live bindings and the default-export interop side by side, then removes all three files it created.

Node.js

const fs = require('node:fs');
const path = require('node:path');
const { pathToFileURL } = require('node:url');

const esmCounterPath = path.join(__dirname, 'counter.mjs');
const cjsCounterPath = path.join(__dirname, 'counter.cjs');
const cjsDefaultPath = path.join(__dirname, 'greeter.cjs');

fs.writeFileSync(esmCounterPath, 'export let counter = 0;\nexport function inc() { counter++; }\n');
fs.writeFileSync(cjsCounterPath, 'let counter = 0;\nfunction inc() { counter++; }\nmodule.exports = { counter, inc };\n');
fs.writeFileSync(cjsDefaultPath, "module.exports = function Greeter(name) { return 'Hi, ' + name; };\n");

(async () => {
  try {
    // ESM import: the namespace object's property is a LIVE binding
    const esmNs = await import(pathToFileURL(esmCounterPath).href);
    console.log('esm import counter before inc():', esmNs.counter);
    esmNs.inc();
    console.log('esm import counter after inc():', esmNs.counter);

    // CJS require + destructure: a snapshot COPY taken at require() time
    const { counter, inc } = require(cjsCounterPath);
    console.log('cjs require counter before inc():', counter);
    inc();
    console.log('cjs require counter after inc() (still the old copy):', counter);

    // module.exports = <function> seen from the importing side as the default export
    const greeterNs = await import(pathToFileURL(cjsDefaultPath).href);
    console.log('cjs module.exports as import default:', greeterNs.default('Dana'));
  } finally {
    fs.unlinkSync(esmCounterPath);
    fs.unlinkSync(cjsCounterPath);
    fs.unlinkSync(cjsDefaultPath);
  }
})();

Output (verified on Node 24)

esm import counter before inc(): 0
esm import counter after inc(): 1
cjs require counter before inc(): 0
cjs require counter after inc() (still the old copy): 0
cjs module.exports as import default: Hi, Dana

counter in the ESM sibling is exported as a live binding: the importing side reads the module’s actual variable, so it sees 1 after inc() runs. The CJS sibling’s { counter, inc } object is destructured — counter at that point is copied out as a plain number, so nothing the sibling does afterwards can change the local counter variable in the importer.

Next: continue this cheat sheet in Module Resolution, which covers how Node finds a specifier on disk in the first place — node_modules lookup, the exports map, and condition ordering.

Mental Model

Think of CJS and ESM as two different postal systems that happen to deliver to the same mailbox (the file on disk). CJS delivers a sealed snapshot — whatever module.exports looked like the instant require() ran, copied out; nothing that arrives later updates it. ESM delivers a live wire to the source module’s own variables — a import { x } from './m.js' binding is not a copy of x, it is a read-only view onto the exporter’s actual x, which is why it updates when the exporter does. __dirname and import.meta.dirname are two different systems for the same underlying question (“what folder is this file in”), and only the ESM one is spelled import.meta.dirname.

Trade-offs

Choice	Benefit	Cost
CommonJS (`require`)	Simple, synchronous, dynamic (`require()` inside an `if`); every existing Node package still works	No top-level `await`; snapshot exports, not live; needs `createRequire` tricks for `import.meta`-only features
ESM (`import`/`export`)	Standard JS module system; static analysis and tree-shaking; live bindings; top-level `await`	Cannot `require()` an ESM file with top-level `await`; `__dirname`/`__filename` do not exist
`"type": "module"` in `package.json`	Explicit, fast — Node does not need to sniff file contents	Every `.js` file in that package must then be valid ESM (use `.cjs` for the exceptions)
Relying on `detect-module` (no `"type"` field)	Works today for ambiguous `.js` files	Slower to resolve (Node must inspect syntax) and less obvious to a reader what module system a file uses

Common Misconceptions

“You can never require() an ESM module.” You usually can — the exception is specifically an ESM file that uses top-level await, which throws ERR_REQUIRE_ASYNC_MODULE because require() must return synchronously.
“__dirname is undefined in an ES module.” It does not exist at all — referencing it throws a ReferenceError, not “gives you undefined”. The direct replacement is import.meta.dirname.
“Importing a CommonJS module from ESM gives you live bindings too.” No — CJS modules never have live bindings, on either side. Live bindings are strictly an ESM-to-ESM feature; importing CJS from ESM still gets a one-time snapshot (wrapped so module.exports appears as default).

Reading AI-generated code

AI-generated Node.js snippets are frequently written from older training data that assumes a pure-CommonJS world, so they mix require() and import/export in the same file, or use __dirname inside a file whose package.json says "type": "module". Both are immediate, loud failures — but only once the file actually runs, not at a casual read.

🐛 Spot the bug

import fs from 'node:fs';

const configPath = __dirname + '/config.json';
const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));

console.log(config);

Show the answer

This file uses import, so it is an ES module — and __dirname simply does not exist in ES modules; referencing it throws ReferenceError: __dirname is not defined, not a silent undefined. The fix is import.meta.dirname (Node 20.11+, no flag needed): const configPath = import.meta.dirname + '/config.json';. If the code needs to support older Node versions too, the portable form is path.dirname(fileURLToPath(import.meta.url)).

What does adding "type": "module" to package.json do? Enables TypeScript compilation Treats all .js files in that package as ESM (ECMAScript Modules) Disables require() globally across all installed packages Tells Node to use the .mjs extension automatically

Which statement about import is true compared to require()? import is synchronous; require() is asynchronous import can appear anywhere in a function body import is static and resolved before any code runs, enabling tree-shaking import only works inside async functions

How do you export a single main value from an ESM file? module.exports = value export main = value export default value exports.default = value

What does this print?

// counter.mjs
export let counter = 0;
export function inc() { counter++; }

// main.mjs
import { counter, inc } from './counter.mjs';
console.log(counter);
inc();
console.log(counter);

0 then 0 — import creates a snapshot copy, just like require() 0 then 1 — import bindings are live and reflect the exporter's later changes A SyntaxError — you cannot export a let binding undefined then undefined

What happens when this runs?

// utils.js — package.json has "type": "module"
import path from 'node:path';
console.log(path.join(__dirname, 'data.json'));

Prints the absolute path to data.json, same as in CommonJS Prints "undefined/data.json" Throws ReferenceError: __dirname is not defined Silently does nothing, because import and __dirname cannot be mixed