CommonJS & ES module interop

Two kinds of module

A module is a JavaScript file that shares some of its values with other files. Node.js has two kinds of module:

• CommonJS is Node's older kind. A file asks for another file with require("./tool"). It shares values by putting them on module.exports.
• ES modules (ESM for short) are the standard kind. Browsers use them too. A file shares values with export and asks for them with import.

The two kinds load files in different ways:

• With CommonJS, require() runs the other file right away, on that line. Then it gives back that file's module.exports.
• With ES modules, Node first reads every file and finds all the import and export lines. It connects them. Only then does it run the code in the files.

You learned why modules exist in Why modules?, and you practiced import & export. This lesson is for Node projects that use both kinds together. Browsers can't run CommonJS files on their own. So every CommonJS example here is about Node, and the lesson's tests run each one in real Node.

A loader is the part of Node that reads a file and runs it. Node has a CommonJS loader and an ES module loader. Before it runs a file, Node picks one of them.

Node does not look for import or require inside the file to decide. It checks these things, in this order:

1. A flag such as --input-type=module. This is only for code you pass to Node as text, which has no file name.
2. The file ending. .cjs always means CommonJS. .mjs always means ES module.
3. For a .js file, the type field in the nearest package.json file. "module" means ES module. "commonjs", or no type at all, means CommonJS.

Try it below. Each button is one file and the type in its nearest package.json. The code on the left is a short copy of Node's rules, and the line that decides is highlighted.

1function decide({ file, nearestType, inputTypeFlag }) {2  if (inputTypeFlag) return inputTypeFlag;3  if (file.endsWith(".cjs")) return "CommonJS";4  if (file.endsWith(".mjs")) return "ES module";5  if (nearestType === "module") return "ES module";6  return "CommonJS";7}

Each row of this table is one file. Read across to see which loader Node uses for it.

So one project can mix both kinds. A project with type: "module" can still keep one CommonJS file named tool.cjs. A CommonJS project can keep one ES module named tool.mjs. This is why the full file name matters when you report a bug.

Node runs each CommonJS file inside a hidden function, called the wrapper. The wrapper gives the file a few local variables:

• require is a function that loads another file.
• module is an object about this file. Its module.exports property holds what the file shares.
• exports is a shortcut. At the start, it points to the same object as module.exports.
• __dirname and __filename hold the folder path and the file path of this file.

When another file calls require() on this file, it gets back module.exports.

// settings.cjs
module.exports = 3;
setTimeout(() => {
  module.exports = 4;
}, 0);

// app.cjs
const value = require("./settings.cjs");
console.log(value);

// cart.cjs
module.exports = { total: 3 };

// app.cjs
const cart = require("./cart.cjs");
cart.total = 4;
console.log(cart.total);

This code has two small Node examples:

• Lines 1 to 9: settings.cjs shares the number 3. A timer later sets module.exports to 4. But app.cjs prints 3. require is synchronous: it finishes on its own line, before the timer runs. So value already holds 3, and the later change can't reach it.
• Lines 11 to 17: cart.cjs shares an object. app.cjs sets its total to 4 and prints 4. Both files hold the same object, so a change made through one name shows through the other.

Step through three cases below. Pick one with the buttons:

• First require: a file is loaded for the first time.
• Cached require: the same file is asked for twice.
• Circular require: two files ask for each other.

1// main.cjs2const cart = require("./cart.cjs");Run3console.log(cart.total([2, 3]));4 5// cart.cjs6const math = require("./math.cjs");7exports.total = (items) => items.reduce(math.add, 0);8 9// math.cjs10exports.add = (a, b) => a + b;

Node keeps every file it has loaded in a cache, a store of files it already ran. It finds them by their full path. This has two effects:

• Slow setup code in a file runs only once.
• Every file that requires it gets the same module.exports object. A change made by one file shows for all of them.

In a circular require, two files require each other. Node puts a file in the cache as soon as it starts running it. So the second file can get the first file's module.exports before the first file has finished filling it in.

One more trap: exports is only a shortcut to module.exports. Adding a property through the shortcut works. Pointing exports at a new object does not change what the file shares.

1// broken.cjs2exports.answer = 42;3exports = { answer: 0 };4console.log(module.exports.answer);5 6// replacement.cjs7module.exports = function greet(name) {8  return "Hello, " + name;9};

An ES module can load a CommonJS file with import. The safest way is a default import, which is an import without curly braces: import pkg from "./lib.cjs". Then pkg is the CommonJS file's whole module.exports value.

A named import uses curly braces, like import { answer } from "./lib.cjs". From a CommonJS file, it only works sometimes. Node has to find the name answer by reading the CommonJS file's text before the file runs. It can find simple lines like exports.answer = 42. It can't always find names that are added in other ways.

ES modules also share variables in a different way. An ES module import is a live binding: a read-only link to the exporting file's variable, not a copy of its value. When the exporting file changes the variable, the importing file sees the new value.

// score.mjs
export let score = 1;
export function addPoint() {
  score += 1;
}

// app.mjs
import { addPoint, score } from "./score.mjs";
console.log(score);
addPoint();
console.log(score);

Run in Node, this prints 1 and then 2. Line 9 prints score, which is 1. Line 10 calls addPoint(), which adds 1 to score inside score.mjs. Line 11 reads through the same live link and prints 2. Compare this with the require example above, where value kept the number it got.

Try the four cases below. Each button shows the code and what current Node prints or throws. Version 22 of Node was used to check them.

1// lib.cjs2exports.answer = 42;3module.exports.extra = "visible";4 5// app.mjs6import pkg, { answer, extra } from "./lib.cjs";7console.log(pkg.answer, answer, extra);8 9// require-esm.cjs10const ns = require("./tool.mjs");11console.log(ns.default, ns.value);

Each row of this table is one way to cross between the two kinds. Read across to see what you get and what to watch for.

Older advice says "CommonJS can't require ES modules." Current Node is more exact. A CommonJS file can require() an ES module, as long as that module doesn't use top-level await. Top-level await is an await written outside any function, so the whole module pauses there.

require must finish on its own line. It can't pause and wait. So if the ES module, or a file it imports, uses top-level await, Node throws the error ERR_REQUIRE_ASYNC_MODULE.

This feature is new. Node added it in version 20.17.0 behind a flag, a command-line option you had to turn on. It works without a flag from Node 20.19.0 and 22.12.0. A project can still turn it off with --no-experimental-require-module. Check which Node version your server runs before you rely on it.

// tool.mjs
export const value = 7;
export default "esm";

// app.cjs
const namespace = require("./tool.mjs");
console.log(namespace.default, namespace.value);

// async-tool.mjs
await Promise.resolve();
export const ready = 9;

// async-app.cjs
async function loadTool() {
  const namespace = await import("./async-tool.mjs");
  console.log(namespace.ready);
}
loadTool();

This code has two Node examples:

• Lines 1 to 7: tool.mjs has no top-level await. So require gives back its namespace object: one object that holds all the module's exports. Line 7 prints esm 7. The default export is on namespace.default, and the named export value is on namespace.value.
• Lines 9 to 18: async-tool.mjs uses top-level await on line 10, so require would fail. Instead, line 15 uses import(), written like a function call. It gives back a promise, and await waits for it. Line 16 prints 9.

Both examples run in Node, not in this page's code editor.

The namespace object from require("./tool.mjs") has the same shape as the object from import * as ns:

• The default export is on ns.default.
• Each named export is on its own name, like ns.value.
• There is no exports shortcut that you could change, as there is in CommonJS.

If you can't be sure that a package has no top-level await, use import(). It gives back a promise, so the CommonJS file can wait for the module.

A package can give different files to different users. It lists them in the exports field of its package.json, called the exports map. Each key in the map is a condition:

• "import" names the file for code that uses import.
• "require" names the file for code that uses require.
• "default" names the file for anything else.

A package with one file for import and another for require is called a dual package. This helps while a package moves from CommonJS to ES modules. But there is a risk. If one app loads the package both ways, Node runs two separate files. Each file has its own variables. So any saved data, like a counter, splits into two copies. This is called the dual package hazard.

In the lab below, pick who loads the package. Node reads the conditions from top to bottom and uses the first one that fits. The panel on the right also shows the two counters: the CommonJS file added 1 once, and the ES module file added 1 twice.

1{2  "name": "address-book",3  "exports": {4    "import": "./counter.mjs",5    "require": "./counter.cjs",6    "default": "./counter.mjs"7  }8}

There are two safer designs:

• Make one file a thin wrapper: a small file that only loads the other file and shares what it got. Then both ways use one copy of the code and its data.
• Publish only an ES module, if all your users can load ES modules.

The goal is one copy of the code for each piece of saved data.

Node helpers in each kind of module

CommonJS files get three local helpers that ES modules don't: require, __dirname, and __filename. In an ES module in Node, use these instead:

• import.meta.dirname for the folder path. import.meta is an object with facts about the current module.
• import.meta.filename for the file path.
• createRequire(import.meta.url), from node:module, when you really need a CommonJS require.

1// CommonJS2console.log(typeof require, typeof __dirname, typeof __filename);3 4// ES module5import { createRequire } from "node:module";6const require = createRequire(import.meta.url);7console.log(import.meta.dirname, import.meta.filename);8console.log(typeof require);

Line 2 runs in a CommonJS file and prints function string string. Lines 5 and 6 make a require inside an ES module. Line 7 prints the folder path and the file path. Line 8 prints function.

Node added import.meta.dirname and import.meta.filename in version 20.11.0. On older Node, build the paths from import.meta.url with the fileURLToPath and dirname functions.

These are Node tools, not browser tools. A browser ES module has import.meta.url, but no file paths. A browser can't run require() either, unless a bundler (a build tool that joins your files) rewrites the code first.

Where you’ll use this

You will need these rules when:

• A test tool says "Cannot use import statement outside a module". Node chose the CommonJS loader for a file that uses import.
• A package's instructions show const tool = require("tool"), but your app uses ES modules.
• Node says "Named export not found" for a CommonJS package.
• A dual package gives you two copies of something that should exist only once.

1import legacy from "legacy-commonjs-package";2const { parse, format } = legacy;3 4export function render(input) {5  return format(parse(input));6}

Line 1 default-imports the CommonJS package and calls it legacy. Line 2 takes the parse and format functions out of it. This simple pattern doesn't depend on Node finding named exports, and it is easy to read.

• “Browsers run CommonJS.” Browsers run plain scripts and ES modules. CommonJS needs Node, or a build tool that rewrites it first.
• “Every CommonJS property is a named ES export.” A named import from CommonJS works only for names Node can find by reading the file's text.
• “exports = {} replaces what the file shares.” It only points the local shortcut at a new object. Use module.exports = ... instead.
• “type: module changes every file ending.” It only changes .js files. .cjs and .mjs always keep their own loader.
• “Dual packages are always safe.” They are safe only when both files share one copy of the code and its data.
• “require keeps a shared number up to date.” It hands over the value it finds at load time. Only a shared object stays shared, so changes to its properties show everywhere.
• “An ES module import copies the value.” A named import is a live link, so later changes made by the exporting file show in the importing file.

Key takeaways

• .cjs means CommonJS. .mjs means ES module. .js follows the type in the nearest package.json.
• require() finishes on its own line and gives back module.exports. Node runs each CommonJS file once and keeps it in a cache.
• A default import of CommonJS is the whole module.exports. A named import from CommonJS works only if Node finds the name.
• In current Node, require() on an ES module gives back its namespace object. It throws if the module uses top-level await.
• A dual package needs one shared copy of its code, or its saved data splits in two.

Up next: Proxy.