CommonJS, require(esm) and dual packages in Node

CommonJS is Node.js’s original module system. A file shares values by putting them on module.exports, and another file loads it with require(), which reads, runs and returns it synchronously, on the spot. ES modules came later and are the language’s standard, and Node.js 24 runs both systems side by side: an ES module can import a CommonJS file, and require() can load an ES module, as a stable feature since Node.js 24.15, provided no module of its graph uses top-level await. Plenty of existing code and many npm packages are CommonJS, so you will read it and mix it with ES modules. This lesson shows how CommonJS works inside, what each direction of interop gives you, what replaces __dirname in an ES module, and how a package with separate CommonJS and ES module builds gets loaded twice in one program, with the fix.

How CommonJS works

Before Node.js runs a CommonJS file, it wraps the file’s code in a function with five parameters and calls it. The parameters are the module system:

// What Node.js gives every CommonJS file: the five parameters of the function it wraps the file in.
/* global require, module, exports, __filename, __dirname, arguments -- CommonJS passes these to each file (for the linter) */
/* eslint-disable @typescript-eslint/no-require-imports -- CommonJS on purpose */
const { basename } = require('node:path');

console.log('parameters of the wrapper function:', arguments.length);
console.log('exports, require, module:', typeof exports, typeof require, typeof module);
console.log('__filename:', basename(__filename), '| __dirname:', basename(__dirname));
console.log('this is module.exports:', this === module.exports);

parameters of the wrapper function: 5
exports, require, module: object function object
__filename: wrapper.cjs | __dirname: basics
this is module.exports: true

• exports, require and module are parameters of that function, not globals, and so are __filename and __dirname, the file’s own path and folder.
• Variables declared at the top of the file are local to the function, so they stay private to the module.
• this at the top level is module.exports, which exports also points to at the start.

require() finds a file, runs it once and keeps its module.exports in a cache keyed by the resolved file name:

// Requires prices.cjs twice, then a module that assigns to exports instead of module.exports.
/* global require -- CommonJS passes these to each file (for the linter) */
/* eslint-disable @typescript-eslint/no-require-imports -- CommonJS on purpose */
const first = require('./prices.cjs');
const second = require('./prices.cjs');

console.log('₹100 with GST:', first.withGst(10000) / 100);
console.log('the same object both times:', first === second);
console.log('kept in require.cache:', Object.keys(require.cache).some((file) => file.endsWith('prices.cjs')));
console.log('wrong-exports.cjs gives:', JSON.stringify(require('./wrong-exports.cjs')));

prices.cjs runs
₹100 with GST: 118
the same object both times: true
kept in require.cache: true
wrong-exports.cjs gives: {}

// A CommonJS module: whatever ends up in module.exports is what require() returns.
/* global require, module -- CommonJS passes these to each file (for the linter) */
/* eslint-disable @typescript-eslint/no-require-imports -- CommonJS on purpose */
console.log('prices.cjs runs');

// No extension: require() tries .js, .json and .node in turn, and finds rates.json.
const rates = require('./rates');

function withGst(paise) {
  return paise + Math.round(paise * rates.gst);
}

module.exports = { withGst };

{ "gst": 0.18 }

// Assigning to `exports` only rebinds a local variable: require() returns module.exports, which is still {}.
/* eslint-disable @typescript-eslint/no-unused-vars -- the assignment below is the mistake this file shows */
/* global exports: writable -- CommonJS passes these to each file (for the linter) */
exports = { gst: 0.18 };

prices.cjs runs appears once: the second require() returned the same object from require.cache. Inside prices.cjs, require('./rates') has no extension: CommonJS tries .js, .json and .node in turn, and here it found rates.json, which it parsed as JSON. wrong-exports.cjs shows the classic mistake: exports = { … } only points the local parameter at a new object, while require() returns module.exports, still the empty object. Add properties with exports.gst = 0.18, or replace the whole value with module.exports = ….

Cycles in CommonJS

When two files require each other, the second one gets the first one’s exports as they are at that moment:

// Starts the cycle by requiring inventory.cjs, then uses both modules once they have finished.
/* global require -- CommonJS passes these to each file (for the linter) */
/* eslint-disable @typescript-eslint/no-require-imports -- CommonJS on purpose */
const inventory = require('./inventory.cjs');

console.log(inventory.reserve('pen'));
console.log(inventory.reserve('notebook'));

inventory.cjs starts
orders.cjs starts
orders.cjs sees these exports of inventory.cjs: stock
inventory.cjs ends
pen: reserved
notebook: out of stock

// inventory.cjs and orders.cjs require each other.
/* global require, exports -- CommonJS passes these to each file (for the linter) */
/* eslint-disable @typescript-eslint/no-require-imports -- CommonJS on purpose */
console.log('inventory.cjs starts');
exports.stock = { pen: 3, notebook: 0 };

const orders = require('./orders.cjs');

exports.reserve = (item) => orders.place(item);
console.log('inventory.cjs ends');

// Required by inventory.cjs while inventory.cjs is still running.
/* global require, exports -- CommonJS passes these to each file (for the linter) */
/* eslint-disable @typescript-eslint/no-require-imports -- CommonJS on purpose */
console.log('orders.cjs starts');
const inventory = require('./inventory.cjs');

console.log('orders.cjs sees these exports of inventory.cjs:', Object.keys(inventory).join(', '));

exports.place = (item) => `${item}: ${inventory.stock[item] > 0 ? 'reserved' : 'out of stock'}`;

inventory.cjs was still running when orders.cjs asked for it, so the cache handed back its unfinished exports, with stock but no reserve. Nothing ran twice and nothing looped. The later calls still worked, because orders.cjs kept a reference to the same exports object, which inventory.cjs went on filling. Had inventory.cjs ended with module.exports = { stock, reserve } instead, orders.cjs would have kept the old, empty object for good. ES modules handle cycles with live bindings instead, so a let, const or class read before its module has run is a ReferenceError there rather than a silent undefined.

Node.js decides per file which system runs it: .cjs is CommonJS and .mjs an ES module, while a .js file follows the "type" field of the nearest package.json; the lesson on running JavaScript lists every case. The examples here use .cjs and .mjs, so they mean the same wherever they are saved. A package.json with a syntax error, such as a trailing comma, stops even a plain node app.js with ERR_INVALID_PACKAGE_CONFIG, because Node.js reads it to decide the file’s type.

Importing CommonJS from an ES module

An ES module can import a CommonJS file directly. The default import is always the file’s module.exports:

// An ES module importing two CommonJS files.
import rates, { gstRate } from './rates.cjs';
import * as namespace from './rates.cjs';
import built from './built.cjs';

console.log('named import from rates.cjs:', gstRate);
console.log('default import is module.exports:', JSON.stringify(rates));
console.log('names on the namespace:', Object.keys(namespace).join(', '));
console.log('built.cjs through its default import:', built.gstRate);

named import from rates.cjs: 0.18
default import is module.exports: {"gstRate":0.18,"currency":"INR"}
names on the namespace: currency, default, gstRate, module.exports
built.cjs through its default import: 0.18

// Exports added one property at a time: a pattern Node.js can read without running the file.
/* global exports -- CommonJS passes these to each file (for the linter) */
exports.gstRate = 0.18;
exports.currency = 'INR';

// module.exports set to whatever a function returns: its names are known only once the file has run.
/* global module -- CommonJS passes these to each file (for the linter) */
function build() {
  return { gstRate: 0.18, currency: 'INR' };
}

module.exports = build();

Named imports are a convenience on top. An ES module’s imports are connected before any code runs, so Node.js cannot run the CommonJS file to see what it exports; it reads the source instead and recognises common patterns, such as exports.gstRate = …. That worked for rates.cjs, whose namespace offers gstRate and currency, the default, and the same value once more under the name 'module.exports'. These named exports are copies made once, not live bindings. built.cjs sets module.exports to whatever a function returns, which no reading of the source can see, so a named import from it fails before anything runs:

// Two mistakes when ES modules meet CommonJS, run with Node.js.
import { session } from './session.mjs';

session(['node esm-imports-cjs/named-from-built.mjs', 'node paths/uses-dirname.mjs']);

$ node esm-imports-cjs/named-from-built.mjs
SyntaxError: Named export 'gstRate' not found. The requested module './built.cjs' is a CommonJS module, which may not support all module.exports as named exports.
[exit status 1]
$ node paths/uses-dirname.mjs
ReferenceError: __dirname is not defined in ES module scope
[exit status 1]

// A named import from built.cjs, whose exports static analysis cannot see.
import { gstRate } from './built.cjs';

console.log(gstRate);

// CommonJS habits in an ES module.
// eslint-disable-next-line no-undef -- the mistake this file shows
console.log(__dirname);

The full message goes on to suggest the fix: import the default and take the property from it, as main.mjs did with built.gstRate. When a named import from a CommonJS package fails, that is the answer that always works.

require() of ES modules in Node.js 24

The other direction used to be impossible: require() of an ES module threw ERR_REQUIRE_ESM. Node.js added it behind a flag in 22.0 and 20.17, turned it on by default in 23.0, 22.12 and 20.19, and declared it stable in 24.15. process.features.require_module tells a program whether it is available.

// CommonJS code loading three ES modules with require() in Node.js 24.
/* global require -- CommonJS passes these to each file (for the linter) */
/* eslint-disable @typescript-eslint/no-require-imports -- CommonJS on purpose */
const money = require('./money.mjs');
console.log('require(money.mjs) gives a namespace with:', Object.keys(money).join(', '));
console.log('new money.default(500).paise:', new money.default(500).paise);

const price = require('./price.mjs');
console.log("price.mjs exports 'module.exports', so require() gives:", typeof price, price(4999));

try {
  require('./slow.mjs');
} catch (error) {
  console.log('require(slow.mjs):', error.code);
}
console.log('process.features.require_module:', process.features.require_module);

require(money.mjs) gives a namespace with: __esModule, currency, default
new money.default(500).paise: 500
price.mjs exports 'module.exports', so require() gives: function ₹49.99
require(slow.mjs): ERR_REQUIRE_ASYNC_MODULE
process.features.require_module: true

// An ES module with a default export and a named export.
export default class Money {
  constructor(paise) {
    this.paise = paise;
  }
}

export const currency = 'INR';

// An ES module that tells require() what to return: the export named 'module.exports'.
export default function price(paise) {
  return `₹${(paise / 100).toFixed(2)}`;
}

export { price as 'module.exports' };

// An ES module with top-level await.
await Promise.resolve();

export const ready = true;

• require() returns the module’s namespace object, so a default export is .default. Node.js adds __esModule: true when the module has a default export, a marker that code compiled from ES modules to CommonJS by build tools looks for; code you write by hand should not depend on it.
• An ES module can choose what require() returns by exporting a value under the string name 'module.exports', as price.mjs does. CommonJS callers then get the function itself, but they lose the module’s other named exports unless those are attached to that value.
• slow.mjs uses top-level await, and require() refused it with ERR_REQUIRE_ASYNC_MODULE: a synchronous call cannot wait for a module graph that waits. The same error comes from top-level await anywhere in the graph, not only in the file you require. CommonJS code can still use import() for such modules.

__dirname, __filename and require() in ES modules

ES modules have no wrapper function, so the five CommonJS variables do not exist in them. The session above showed the error you get, ReferenceError: __dirname is not defined in ES module scope. Here is what replaces them:

// What replaces __dirname, __filename and require() in an ES module.
import { readFileSync } from 'node:fs';
import { createRequire } from 'node:module';
import { basename, join } from 'node:path';

console.log('import.meta.filename ends with:', basename(import.meta.filename));
console.log('import.meta.dirname ends with:', basename(import.meta.dirname));

const greeting = readFileSync(join(import.meta.dirname, 'greeting.txt'), 'utf8').trim();
console.log('read next to the module:', greeting);
console.log('the same through a URL:', readFileSync(new URL('./greeting.txt', import.meta.url), 'utf8').trim() === greeting);

const require = createRequire(import.meta.url);
console.log('createRequire() loads JSON synchronously:', require('./settings.json').currency);
console.log('typeof __dirname here:', typeof __dirname);

import.meta.filename ends with: paths.mjs
import.meta.dirname ends with: paths
read next to the module: Namaste from a file next to the module
the same through a URL: true
createRequire() loads JSON synchronously: INR
typeof __dirname here: undefined

Namaste from a file next to the module

{ "currency": "INR" }

import.meta.filename and import.meta.dirname are the module’s own path and folder (Node.js 20.11 and later), and import.meta.url is its file: URL, which new URL('./greeting.txt', import.meta.url) turns into the address of a file next to it. Both point at the module’s folder, not the folder the program was started from, so a script finds its files wherever someone runs it. When an ES module needs a synchronous require(), for example for a package that is CommonJS only, createRequire(import.meta.url) makes one that resolves relative to the module.

One package for import and require

A package’s "exports" field in package.json lists its public entry points. Anything it does not list cannot be imported by its package name, which keeps internal files internal. An entry can depend on conditions, which Node.js checks in the order they are written: "import" matches import and import(), "require" matches require(), "module-sync" matches both for an ES module without top-level await, "node" matches any Node.js, and "default" matches everything and goes last. The "imports" field adds private aliases that start with #, usable only inside the package.

The tempting design is two builds, one ES module behind "import" and one CommonJS file behind "require". Here both versions of a package called paise are used by an app that has an ES module and a CommonJS file, each using the package by its own name, which a package with "exports" may do:

{
  "name": "paise",
  "version": "1.0.0",
  "type": "module",
  "exports": {
    ".": {
      "import": "./money.mjs",
      "require": "./money.cjs"
    }
  }
}

// The ES module build of the package.
console.log('money.mjs runs');

export class Money {
  constructor(paise) {
    this.paise = paise;
  }
}

// The CommonJS build of the same package: the same class, written again.
/* global module -- CommonJS passes these to each file (for the linter) */
console.log('money.cjs runs');

class Money {
  constructor(paise) {
    this.paise = paise;
  }
}

module.exports = { Money };

// CommonJS code that uses the package by its name; require() takes the "require" condition of "exports".
/* global require, module -- CommonJS passes these to each file (for the linter) */
/* eslint-disable @typescript-eslint/no-require-imports -- CommonJS on purpose */
const { Money } = require('paise');

module.exports = { price: new Money(4999) };

// An ES module that uses the package by its name (a package may import itself), and the CommonJS file too.
import { Money } from 'paise';
import legacy from './legacy.cjs';

console.log('legacy.price instanceof Money:', legacy.price instanceof Money);

{
  "name": "paise",
  "version": "2.0.0",
  "type": "module",
  "exports": {
    ".": "./money.mjs"
  },
  "imports": {
    "#format": "./format.mjs"
  }
}

// The only build of the package, an ES module. "#format" is a private alias from the "imports" field.
import { rupees } from '#format';

console.log('money.mjs runs');

export class Money {
  constructor(paise) {
    this.paise = paise;
  }

  toString() {
    return rupees(this.paise);
  }
}

// Tries to import a file that the package's "exports" does not list.
import { rupees } from 'paise/format.mjs';

console.log(rupees(100));

// Both versions of the package, run with Node.js, and an import of a file the package does not export.
import { session } from '../session.mjs';

session(['node hazard/app.mjs', 'node fixed/app.mjs', 'node fixed/peek.mjs']);

$ node hazard/app.mjs
money.mjs runs
money.cjs runs
legacy.price instanceof Money: false
$ node fixed/app.mjs
money.mjs runs
legacy.price instanceof Money: true
legacy.price is ₹49.99
$ node fixed/peek.mjs
Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package subpath './format.mjs' is not defined by "exports" in ./fixed/package.json imported from ./fixed/peek.mjs
[exit status 1]

With two builds, both files ran, so the program held two unrelated Money classes, and a price made by the CommonJS side was not an instanceof the class the ES module side imported. The same split doubles anything a package keeps in module state: a cache, a registry of plug-ins or a configuration set by one side is invisible to the other. This is the dual package hazard. In the fixed version, "exports" sends everyone to one ES module, require() loads that same module, and the check is true. fixed/peek.mjs also shows the encapsulation: paise/format.mjs is not in "exports", so importing it by the package name fails with ERR_PACKAGE_PATH_NOT_EXPORTED, while the package itself reaches it through its private #format alias.

So for a new package, publish ES modules only and let require() load them, which Node.js 20.19, 22.12 and every later release can do. Keep top-level await out of the package’s entry points, or CommonJS users get ERR_REQUIRE_ASYNC_MODULE. If you must keep a CommonJS build for older Node.js versions, keep the real code, and any state, in one of the two builds and make the other a thin wrapper around it, so that only one copy can exist.

Exercise: a tiny require() with a cache

makeRequire() should run each module’s function once, keep its exports in a cache, hand a cycle the exports filled in so far, throw MODULE_NOT_FOUND for unknown names, and forget a module whose function threw. The sample tests check each of those.

// mini-require.mjs: the core of CommonJS's require() (the exercise of lesson javascript/commonjs-and-interop).
export function makeRequire(modules) {
  function require(name) {
    const module = { exports: {} };
    modules[name](module.exports, require, module);
    return module.exports;
  }
  return require;
}

import { test, assert } from 'mysmartcopilot:test';
import { makeRequire } from './mini-require.mjs';

test('returns module.exports, filled through exports or replaced', () => {
  const require = makeRequire({
    rates: (exports) => {
      exports.gst = 0.18;
    },
    add: (exports, require, module) => {
      module.exports = (a, b) => a + b;
    },
  });
  assert.deepEqual(require('rates'), { gst: 0.18 });
  assert.equal(require('add')(2, 3), 5);
});

test('runs each module once and returns the cached exports', () => {
  let runs = 0;
  const require = makeRequire({
    counter: (exports) => {
      runs += 1;
      exports.count = 0;
    },
  });
  const first = require('counter');
  const second = require('counter');
  assert.equal(first, second);
  assert.equal(runs, 1);
});

test('a cycle gets the exports filled in so far', () => {
  // Without a cache the two modules would require each other for ever; stop after a few runs instead.
  let runs = 0;
  const guard = () => {
    runs += 1;
    if (runs > 4) throw new Error('the two modules keep running each other: is a module cached before its function runs?');
  };
  const require = makeRequire({
    inventory: (exports, require) => {
      guard();
      exports.stock = 3;
      const orders = require('orders');
      exports.sawOrders = typeof orders.place;
    },
    orders: (exports, require) => {
      guard();
      const inventory = require('inventory');
      exports.place = () => 'placed';
      exports.sawStock = inventory.stock;
      exports.sawSawOrders = inventory.sawOrders;
    },
  });
  const inventory = require('inventory');
  assert.equal(inventory.sawOrders, 'function');
  assert.equal(require('orders').sawStock, 3);
  assert.equal(require('orders').sawSawOrders, undefined);
  assert.equal(runs, 2);
});

test('an unknown name throws an Error with code MODULE_NOT_FOUND', () => {
  const require = makeRequire({});
  try {
    require('missing');
    assert.ok(false, 'require("missing") should throw');
  } catch (error) {
    assert.equal(error.code, 'MODULE_NOT_FOUND');
    assert.ok(error instanceof Error);
  }
});

test('a module that threw is run again on the next require', () => {
  let runs = 0;
  const require = makeRequire({
    flaky: (exports) => {
      runs += 1;
      if (runs === 1) throw new Error('first run fails');
      exports.ok = true;
    },
  });
  assert.throws(() => require('flaky'), Error);
  assert.deepEqual(require('flaky'), { ok: true });
  assert.equal(runs, 2);
});

test('each require has its own cache', () => {
  let runs = 0;
  const modules = { once: () => (runs += 1) };
  makeRequire(modules)('once');
  makeRequire(modules)('once');
  assert.equal(runs, 2);
});

Interview questions

Fresher · What is the difference between module.exports and exports in CommonJS?

module.exports is the value that require() returns for a file. exports is a parameter of the wrapper function that starts out pointing at the same object, as a shortcut. Adding properties through either one is the same thing: exports.rate = 0.18 puts rate on module.exports. Assigning to them is not: module.exports = fn replaces what the file exports, while exports = fn only points the local parameter at something else, and require() still returns the original, empty object. So use exports.name = … to add exports, use module.exports = … to export one function or class, and never assign to exports itself. After module.exports has been replaced, exports no longer points at it either.

Key takeaways

• A CommonJS file runs inside a function whose parameters are exports, require, module, __filename and __dirname; require() runs a file once and caches its module.exports.
• In a cycle, CommonJS hands back the exports filled in so far; replacing module.exports at the end leaves the other module with the old object.
• An ES module imports CommonJS as a default export, module.exports, plus the named exports Node.js can find by reading the source; fall back to the default import when a name is not found.
• In Node.js 24, require() loads ES modules and returns their namespace, unless top-level await appears anywhere in the graph (ERR_REQUIRE_ASYNC_MODULE).
• In ES modules, use import.meta.dirname, import.meta.filename, import.meta.url and createRequire().
• Separate CommonJS and ES module builds behind "require" and "import" load a package twice; publish one ES module build, or make one build a wrapper around the other.