Modules

Modules

Prerequisites assumed: closures, lexical scope, import/export syntax, and the browser/Node execution model. This chapter covers how ES modules actually load, evaluate, and link — and where they differ from CommonJS.

Static Structure

ES modules are static: their imports and exports are resolved before any code runs. The parser walks the file, collects import declarations, and builds a dependency graph before evaluation. This is why import must be at the top level — you cannot import conditionally or from inside a function with the static syntax.

// logger.js
export function log(msg) {
  console.log(`[${new Date().toISOString()}] ${msg}`);
}
export default class Logger { /* ... */ }

// app.js — bindings, not copies
import Logger, { log } from './logger.js';
log('started');

The key distinction from CommonJS: import { log } creates a live binding to the exporting module's variable. If logger.js later reassigns an exported let, importers see the new value. In CommonJS, require() copies values at require time — objects are shared, primitives are not.

Evaluation Semantics

1. Parse — the loader resolves all specifiers and fetches the graph.
2. Instantiate — module records are built; exported bindings are linked before execution.
3. Evaluate — module bodies run once, depth-first, in dependency order. The result is cached.

Because evaluation is cached per-URL, a module is a natural singleton. Cycles are allowed but risky: during evaluation of a cyclic import, bindings exist but are uninitialized, so accessing a const binding too early throws a ReferenceError (a temporal dead zone violation across module boundaries).

// a.js
import { b } from './b.js';
export const a = 'a';
console.log('a evaluates', b);

// b.js
import { a } from './a.js';
console.log('b evaluates', typeof a); // 'undefined' — TDZ if read before init
export const b = 'b';

Dynamic Import

import() returns a promise and can appear anywhere, enabling code splitting:

button.addEventListener('click', async () => {
  const { renderChart } = await import('./chart.js');
  renderChart(data);
});

This trades static analyzability for laziness. Bundlers can only split code they can see statically; fully dynamic specifiers (await import(someVariable)) defeat tree-shaking.

Interop and Gotchas

In Node, a file is an ES module only if "type": "module" is set in package.json or the extension is .mjs. The most common failure is mixing systems: require() cannot load an ES module synchronously, and top-level await only works in modules.

100%

Show diagram source

flowchart TD
  A[Parse entry module] --> B[Resolve all imports recursively]
  B --> C[Instantiate: link bindings]
  C --> D[Evaluate dependencies depth-first]
  D --> E[Evaluate module body once]
  E --> F[Cache result per URL]