Modules

ES modules (ESM) are JavaScript's built-in module system. In the browser you opt in with <script type="module">; in Node with .mjs files or "type": "module" in package.json.

A module is a file with its own top-level scope. Variables declared in it don't leak into the global scope, and nothing gets in or out except through explicit export and import. Before modules, every <script> shared one global scope: two libraries defining utils overwrote each other, and you had to order <script> tags by hand so dependencies loaded first. Modules fix both — each file declares exactly what it needs, and the engine works out the order.

The mental model: exports are named slots, and imports are wires connected to those slots before any code runs. An import doesn't copy a value; it gives your file a read-only view of a variable that lives in the other module. A default export is not a special mechanism either — it's just an export whose name happens to be default.

Module code is also always strict mode, top-level this is undefined, and in the browser module scripts are deferred automatically (they run after the HTML is parsed) and must be served over HTTP(S) — loading them from a file:// page fails with a CORS error in most browsers.

There are two kinds of export:

// math.js
export const PI = 3.14159;
export function add(a, b) {
  return a + b;
}
const secret = 42; // not exported → private to the file

// main.js
import { PI, add } from "./math.js";
import { add as sum } from "./math.js"; // rename

// api.js
const api = "1234";
export default api;

// Other valid forms (still one per file):
//   export default "1234";
//   export default function getApi() {}
// ❌ export default let api = "1234";

// main.js
import api from "./api.js";
import whatever from "./api.js"; // same value — you pick the name

// Both in one import
import React, { useState, useEffect } from "react";

// Namespace import: group every named export into one object
import * as utils from "./utils.js";
utils.add(1, 2);
utils.default; // the default export, if there is one

// dflt.js
let value = "first";
export default value;              // the value at this moment
export { value as liveDefault };   // a live binding to the variable
export function change() {
  value = "second";
}

// main.js
import snap, { liveDefault, change } from "./dflt.js";
change();
console.log(snap, liveDefault); // first second

A re-export forwards another module's exports through the current file without using them there. The main use is a "barrel": one index.js per folder, so the rest of the app imports from ./components instead of knowing the path of every file inside it.

// components/index.js — a "barrel" file
export { Button } from "./Button.js";
export { default as Modal } from "./Modal.js";
export * from "./icons.js";

button.addEventListener("click", async () => {
  const { openEditor } = await import("./editor.js"); // downloaded only when needed
  openEditor();
});

// React
const Settings = React.lazy(() => import("./Settings.jsx"));

// Works in CommonJS too — the way to load an ESM-only package from CJS.
// CommonJS has no top-level await, so wrap it in an async function:
async function loadChalk() {
  const { default: chalk } = await import("chalk");
  return chalk;
}

CommonJS (CJS) is Node's original module system: require to import, module.exports (or exports) to export.

Under the hood, Node wraps every CommonJS file in a function before running it: (function (exports, require, module, __filename, __dirname) { …your file… }). That's where those "globals" come from — they're parameters. It's also why top-level variables stay private to the file (they're local to the wrapper) and why top-level this is module.exports.

require(path) is an ordinary, synchronous function call: resolve the path to a file, check the cache, and if it's not cached, create a module object, run the file's wrapper, and return module.exports. Whatever the file put in module.exports by the time it finished is what the caller gets.

// greet.js — exporting a single value
module.exports = function () {
  console.log("Hello from CommonJS");
};

// math.js — exporting several things
exports.add = (a, b) => a + b;
exports.PI = 3.14159;
// same as: module.exports = { add, PI };

// main.js
const greet = require("./greet");
const { add, PI } = require("./math"); // extension optional
greet();

ES module imports are live, read-only views of the exported variable. CommonJS gives you copied values: whatever was put into module.exports, as it was at that moment.

To be precise about where the copy happens: require returns the same module.exports object every time — a reference, not a copy. The copying happens one step earlier. When a module writes module.exports = { count }, the value of count is copied into a property, and that property is not connected to the variable afterwards. Destructuring const { count } = require(…) then copies that value again into your own variable. ESM never copies: the importer's count is the exporter's variable, seen through a read-only window.

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

// main.mjs
import { count, increment } from "./counter.mjs";
console.log(count); // 0
increment();
console.log(count); // 1 ✅ sees the update

count = 5; // TypeError: Assignment to constant variable

// counter.js
let count = 0;
module.exports = {
  count,
  increment() {
    count++;
  },
};

// main.js
const { count, increment } = require("./counter");
console.log(count); // 0
increment();
console.log(count); // 0 ❌ still the old copy

// counter.js
let count = 0;
module.exports = {
  get count() {
    return count;
  },
  increment() {
    count++;
  },
};

// main.js
const counter = require("./counter");
const { count } = require("./counter");
counter.increment();
console.log(counter.count, count); // 1 0

The "Loading" and "Analysis" rows are the root of most of the others. An ES module graph is processed in three phases: load and parse every file reachable from the entry point, link every import to its export, and only then evaluate the code — dependencies first. CommonJS has one phase: run the file, and load each dependency the moment a require call is reached. You can see the ESM ordering directly:

// order-a.js
console.log("a.js runs");
export const a = "A";

// order-b.js
console.log("b.js runs");
export const b = "B";

// main.js
console.log("main.js body starts");
import { a } from "./order-a.js";
import { b } from "./order-b.js";
console.log(a, b);

// Output:
// a.js runs
// b.js runs
// main.js body starts
// A B

Before ES2015 there was no module system in the language, so the community made two:

• CommonJS — synchronous require, designed for servers where files are on local disk. Became Node's system.
• AMD (Asynchronous Module Definition, e.g. RequireJS) — asynchronous loading designed for browsers, where every module is a network request.

The split came down to latency. Reading a file from local disk takes microseconds, so making require block until the file is ready is fine on a server. In a browser, a blocking require would freeze the page during every network request, so AMD declared dependencies up front and received them in a callback once they'd all arrived.

// AMD
define(["jquery", "./utils"], function ($, utils) {
  return { init() { /* ... */ } };
});

// UMD — one file that works with AMD, CommonJS, or a plain <script>
(function (root, factory) {
  if (typeof define === "function" && define.amd) {
    define([], factory);          // AMD loader present
  } else if (typeof module === "object" && module.exports) {
    module.exports = factory();   // CommonJS (Node)
  } else {
    root.myLib = factory();       // plain <script>: attach to the global
  }
})(this, function () {
  return { hello: () => "hi" };
});

A module's top-level code runs once, the first time it's imported. After that, every importer gets the same cached instance. (Same for CommonJS, via require.cache.) So module-level state is naturally shared — a module is effectively a singleton.

The mental model is a registry keyed by location: the first time a module's URL (ESM) or resolved file path (CommonJS) is requested, the engine runs it and stores the result. Every later request for that same key gets the stored result back without running anything. This is why you rarely need a Singleton class in JavaScript (see Singleton) — the module system already gives you one instance per file.

// store.js
const globalMap = new Map(); // created once, no matter how many files import this

export default {
  getInstance() {
    return globalMap;
  },
};

import store from "./store.js";
store.getInstance().set("user", "Rohit");

import store from "./store.js";
store.getInstance().get("user"); // "Rohit" — same Map