How JavaScript Modules Work: Scope, Live Bindings and Cycles

A module is a file with its own scope that decides what to share. JavaScript has two module systems in daily use, ES modules (import/export) and CommonJS (require/module.exports), and they differ in ways that cause real bugs: whether you get a live binding or a copied value, when code runs, and what happens when two modules import each other. This post explains both, with the loading steps drawn out and every example run in Node.js.

Why It Matters

Module behavior decides:

• whether your feature flags update
• whether two parts of an app share one cache or two
• why a circular import crashes only in production builds
• why “dual” packages sometimes load twice

Bundlers, test runners and frameworks all build on these rules, so understanding them makes their error messages readable.

Module Scope

Every module has its own top-level scope. Variables declared there are invisible to other modules unless exported, and ES modules are always in strict mode with a top-level this of undefined. Before modules, everything shared one global scope, which is why old code wrapped files in immediately invoked functions.

ES Modules Load in Three Phases

An ES module graph is loaded before any of it runs:

Because imports are found by parsing, they must be static: import declarations sit at the top level with string literals. That is what lets bundlers tree-shake unused exports. For loading at runtime, there is import(), which returns a promise.

Live Bindings vs Copied Values

In ES modules, an import is a live, read-only binding to the exporter’s variable. In CommonJS, require returns an object, and destructuring copies the values out of it at that moment:

export let count = 0;
export function increment() {
  count++;
}

import { count, increment } from './counter.mjs';
increment();
console.log(count); // 1: the binding is live
 
count = 5; // TypeError: Assignment to constant variable.

// counter.cjs
let count = 0;
function increment() {
  count++;
}
module.exports = { count, increment };
 
// main.cjs
const { count, increment } = require('./counter.cjs');
increment();
console.log(count); // 0: count was copied when module.exports was built

Practical consequences:

• In ES modules, export a function (getCount()) or an object if consumers must see updates, and say so in the API. Live bindings work, but they surprise readers.
• In CommonJS, require('./counter.cjs').count reads the exports object each time, but that property still holds the copied 0; only an exported getter or object reflects changes.
• Imports are read-only for the importer. Only the exporting module can change its variable.

Every Module Is a Singleton

A module runs once, and every importer receives the same instance:

import './analytics.mjs'; // runs analytics.mjs
import './analytics.mjs'; // cached: does not run again
 
const a = await import('./analytics.mjs');
const b = await import('./analytics.mjs');
a === b; // true

• Module-level variables are shared state. A const cache = new Map() at the top of a module is one cache for the whole app. Convenient, and also how tests leak state into each other; most test runners isolate modules per test file for this reason.
• The cache is keyed by the resolved URL or path. The same package installed twice (different versions in node_modules), or imported once as ESM and once as CommonJS, is two modules with two copies of its state. That is the root of “two copies of React” errors.

Circular Imports

A cycle (A imports B, and B imports A) is allowed in both systems, but evaluation still has to start somewhere, so one module runs while the other is only partly initialized.

ES modules link first, so the bindings exist but are uninitialized. Reading a let, const or class export too early throws:

// a.mjs
import { b } from './b.mjs';
export const a = 'A';
 
// b.mjs
import { a } from './a.mjs';
export const b = 'B';
console.log(a); // ReferenceError: Cannot access 'a' before initialization

Running a.mjs first evaluates b.mjs (its dependency), and at that point a.mjs hasn’t reached export const a. Function declarations are hoisted and initialized during linking, so calling an exported function from the other side of a cycle works, as long as the function doesn’t itself read an uninitialized binding.

CommonJS returns the partially filled module.exports instead of throwing:

// a.cjs
exports.loaded = false;
const b = require('./b.cjs');
exports.loaded = true;
 
// b.cjs
exports.loaded = false;
const a = require('./a.cjs');
console.log(a.loaded); // false: a.cjs is still in progress
exports.loaded = true;

That doesn’t crash, but you silently get undefined or stale values. Both failure modes have the same fix:

Going Deeper: Packages, Two Module Systems and Top-Level Await

The rules above explain one program. Real applications pull in hundreds of packages, some written as ES modules, some as CommonJS, and that is where the subtle production bugs live.

The Dual Package Hazard

Many packages ship two builds, one ES module and one CommonJS, and pick between them with the exports field in package.json. If your code imports the package while a dependency requires it, Node.js can load both builds. You now have two copies of the same module, each with its own state:

• Symptoms: a configured client that “forgets” its configuration, a plugin registry with missing plugins, or error instanceof SomeError returning false for an error that clearly is one.
• Package authors avoid it by keeping state in only one build (for example, a CommonJS core with a thin ES module wrapper) or by shipping a single format.
• As a consumer, check npm ls <package> and your bundler output for duplicate copies.

Mixing the Two Systems

• An ES module can import CommonJS: it receives module.exports as the default export, plus named exports Node.js can detect statically.
• CommonJS can load ES modules with await import(). Since Node.js 22.12 and 20.19, require() can also load an ES module directly, as long as its module graph has no top-level await.

Top-Level Await Pauses the Graph

An ES module can await at its top level, for example to load configuration.

• While it waits, every module that imports it waits too, because evaluation follows the dependency graph.
• One slow top-level await deep in a shared module delays startup for everything above it, and a rejected one fails the whole import.
• Keep top-level await to entry points, and keep shared libraries free of it.

ES Modules vs CommonJS at a Glance

For new code, use ES modules. They are the standard, work natively in browsers and Node.js, and make dependencies visible to tools.

Test Yourself

Each challenge spans several files. Predict what node main.mjs (or main.cjs) prints, then open the answer. Every answer was checked by running the files with Node.js 24.

export let count = 0;
export default count;
export function inc() {
  count++;
}

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

let count = 0;
module.exports = {
  get count() {
    return count;
  },
  inc() {
    count++;
  },
};

const counter = require('./counter.cjs');
const { count } = counter;
counter.inc();
console.log(counter.count, count);

console.log('loading log');
export const id = Math.random();

import { id } from './log.mjs';
export const a = id;

import { a } from './a.mjs';
import { id } from './log.mjs';
console.log(a === id);

console.log('b body');

console.log('a body');
import './b.mjs';

import './a.mjs';
console.log('main body');

import { b } from './b.mjs';
export const a = 'A';
console.log('a sees', b);

import { a } from './a.mjs';
export const b = 'B';
console.log('b sees', a);

import './a.mjs';

Key Takeaways

Related reading: the hidden cost of mutable state covers why shared module state needs care, and execution contexts and closures explains the temporal dead zone behind the cycle error.

Sources

• Node.js docs: Dual CommonJS/ES module packages
• Node.js docs: Loading ECMAScript modules using require()
• V8 blog: Top-level await
• MDN: JavaScript modules
• Node.js docs: Modules: ECMAScript modules and CommonJS cycles
• Lin Clark, Mozilla Hacks: ES modules: A cartoon deep-dive