Modules (ESM)

Organising JavaScript into reusable files — import, export, named vs default, and ESM vs CommonJS.

What it is, in plain English: A module is a JavaScript file that explicitly exports what it wants to share and imports what it needs from other files. Modules solve the problem of large programs becoming one tangled mess — they let you split code into focused, reusable pieces. ES Modules (ESM) is the standard: use 'export' to share, 'import' to use. Node.js also supports CommonJS (require/module.exports) — understanding both is essential for working in the JS ecosystem.

Where this bites you

In Node's ES modules, an import path is a URL, not a search. import { add } from "./math" doesn't try ./math.js, ./math/index.js or anything else: Node looks for a file named exactly math, finds nothing, and stops before running a single line. It catches people because bundlers such as webpack and Vite, and many TypeScript setups, do fill in the extension, so the same import works in one project and fails in the next.

// package.json: { "type": "module" }

// math.js
export function add(a, b) {
  return a + b;
}

// app.js
import { add } from "./math";      // no extension
console.log(add(2, 3));

// $ node app.js
// Error [ERR_MODULE_NOT_FOUND]: Cannot find module '.../math' imported from .../app.js
// Did you mean to import "./math.js"?

Splitting code into reusable files

As programs grow, putting everything in one file becomes unmanageable. Modules let you split code into focused files — one file for maths utilities, one for user-related functions, one for API calls — and connect them with import and export.

Exporting from a module

// math.js — a module that exports useful maths functions

// Named exports — you can have many:
export function add(a, b)      { return a + b; }
export function subtract(a, b) { return a - b; }
export function multiply(a, b) { return a * b; }
export const PI = 3.14159265;

// Or export at the bottom (equivalent):
function divide(a, b) {
  if (b === 0) throw new Error("Cannot divide by zero");
  return a / b;
}
export { divide };

// user.js — a module with a default export

// Default export — only ONE per module:
export default class User {
  constructor(name, email) {
    this.name  = name;
    this.email = email;
  }
  greet() { return `Hello, I'm ${this.name}`; }
}

// You can mix default and named exports:
export const ROLES = ["admin", "user", "viewer"];

Importing from a module

// app.js — using the modules above

// Named imports — curly braces, exact names:
import { add, multiply, PI } from "./math.js";

console.log(add(2, 3));           // 5
console.log(multiply(PI, 2));     // 6.28...

// Default import — no curly braces, any name you choose:
import User from "./user.js";

const alice = new User("Alice", "alice@example.com");
console.log(alice.greet());       // "Hello, I'm Alice"

// Import both default and named:
import User, { ROLES } from "./user.js";
console.log(ROLES);               // ["admin", "user", "viewer"]

// Import everything as a namespace object:
import * as Math from "./math.js";
console.log(Math.add(2, 3));      // 5
console.log(Math.PI);             // 3.14159265

// Rename on import (avoid naming conflicts):
import { add as mathAdd } from "./math.js";
import { add as vectorAdd } from "./vectors.js";

Using modules in the browser

<!-- Use type="module" on your script tag -->
<script type="module" src="app.js"></script>

<!-- Inline module -->
<script type="module">
  import { add } from "./math.js";
  console.log(add(1, 2));
</script>

Important: modules are always in strict mode automatically. They have their own scope — variables don't leak to the global window. They're deferred by default (like defer attribute).

Using modules in Node.js

// Option 1: use .mjs extension
// math.mjs — same export syntax as above

// Option 2: add "type": "module" to package.json
// {
//   "type": "module"
// }
// Then .js files use ESM syntax

// With "type": "module" in package.json:
// math.js uses: export function add...
// app.js uses:  import { add } from "./math.js"

That's why the Node.js example above writes "./math.js" in full. For relative imports, Node's ES module loader uses the path exactly as written, so the file name has to include its extension (and a folder import has to name its file, as in "./utils/index.js"). Recent versions of Node print a Did you mean hint, as shown above, but they still refuse to guess:

// app.js
import { add } from "./math.js";   // full file name, extension included
console.log(add(2, 3));

// $ node app.js
// 5

Try It Yourself

// Modules run in their own scope — variables don't leak to global
// The Try It editor can demonstrate module concepts inline:

// Simulating named exports and imports:
// (In real code this would be across separate .js files)

// --- math.js would contain: ---
function add(a, b)      { return a + b; }
function subtract(a, b) { return a - b; }
function multiply(a, b) { return a * b; }
const PI = 3.14159265;
// export { add, subtract, multiply, PI };

// --- utils.js would contain: ---
function formatCurrency(amount) {
  return `$${amount.toFixed(2)}`;
}
function clamp(n, min, max) {
  return Math.min(Math.max(n, min), max);
}
// export default formatCurrency;  // default export
// export { clamp };               // named export

// Using them (import { add, PI } from './math.js'):
const result = add(multiply(3, 4), subtract(10, 2));
console.log(`Result: ${result}`);    // 14

// Default import: import formatCurrency from './utils.js'
const price = 29.99;
console.log(formatCurrency(price));   // "$29.99"

// Dynamic import (real async import):
console.log("Modules let you split code across files.");
console.log("Each file is its own scope — no global pollution.");
console.log("Tree-shaking removes unused exports in production builds.");

CommonJS, dynamic imports, and circular dependencies

CommonJS — Node.js legacy format

// math.cjs — CommonJS module (old Node.js style)
function add(a, b) { return a + b; }
const PI = 3.14159;

module.exports = { add, PI };       // export as object
// Or:
module.exports.add = add;
module.exports.PI  = PI;

// app.cjs — using CommonJS
const { add, PI } = require("./math.cjs");  // destructure
const math = require("./math.cjs");          // or as namespace
console.log(math.add(1, 2));   // 3

ESM vs CommonJS — the key differences

// ESM                              // CommonJS
import x from "./x.js"             const x = require("./x")
import { y } from "./y.js"         const { y } = require("./y")
export default fn                   module.exports = fn
export { fn }                       module.exports.fn = fn

// ESM: static (resolved at parse time, enables tree-shaking)
// CJS: dynamic (resolved at runtime, can use variables in require())
const mod = require(condition ? "./a" : "./b");  // CJS can do this
// import ... from condition ? "a" : "b"  // ESM cannot (use dynamic import)

Dynamic import() — load modules on demand

// Load a module only when needed (returns a Promise):
async function loadChart() {
  const { Chart } = await import("./chart.js");
  new Chart(canvas, data);
}

// Conditionally load based on environment:
const module = await import(
  process.env.NODE_ENV === "test" ? "./mock-api.js" : "./real-api.js"
);

// Code-split heavy features (common in React/Vue/Next.js apps):
button.addEventListener("click", async () => {
  const { openModal } = await import("./modal.js");
  openModal();
});

Circular dependencies

// a.js
import { b } from "./b.js";
export const a = "A uses " + b;  // b might be undefined here!

// b.js
import { a } from "./a.js";
export const b = "B uses " + a;  // a might be undefined here!

// ESM handles circulars via live bindings — values update when exports update.
// But circular deps are usually a sign of poor module design.
// Solution: extract shared code into a third module that neither imports the other.

Module record internals, live bindings, and the module map

The module system in the ECMAScript spec (§16)

ES modules are represented as Module Records. The loading process has three phases:

Parse — source text is parsed, import/export bindings are identified
Link — export bindings are resolved; import bindings in each module are connected to the corresponding export in the exporting module via Indirect Bindings in the Module Environment Record
Evaluate — module body executes top-to-bottom; exports become live

Live bindings — ESM's critical distinction from CJS

// counter.js
export let count = 0;
export function increment() { count++; }

// app.js
import { count, increment } from "./counter.js";

console.log(count);   // 0
increment();
console.log(count);   // 1 — live binding! the import reflects the current value

// In CommonJS this would NOT work:
// const { count } = require("./counter");
// count would be 0 forever — it's a copy, not a live reference

The module map and caching

Each realm maintains a module map — a map from (URL string, module type) to Module Record. The first time a module is imported, it's fetched, parsed, linked, and evaluated; the result is stored in the map. Subsequent imports of the same URL return the cached Module Record without re-evaluating. This means modules are singletons — all importers share the same module instance.

import.meta

// import.meta is an object specific to each module:
console.log(import.meta.url);   // "file:///path/to/module.js" in Node.js
                                 // "https://..." in browser

// Resolve paths relative to the current module (Node.js):
import { createRequire } from "module";
import { fileURLToPath } from "url";
import { dirname, join } from "path";

const __filename = fileURLToPath(import.meta.url);
const __dirname  = dirname(__filename);
const dataPath   = join(__dirname, "data.json");

// import.meta.resolve (ES2024, Node.js v20.6+):
const resolved = import.meta.resolve("./utils.js");  // absolute URL

Official Sources

The Codex links only to official documentation and the ECMAScript specification. No third-party tutorials.