Modules through a bundler

A module system rebuilt early

A bundler is a build tool that reads an entry module, follows its imports, and writes files the browser can load. It does this before a visitor opens the page. The browser still runs JavaScript modules or emitted runtime code, but the bundler has already made many loading decisions.

This goes deeper than the everyday bundlers lesson. It follows the module records ideas from module records and continues from module loading in Node.js.

Building the module graph

The entry file is the first file a bundler packs. Each static import is an edge to another file. Reading those edges repeatedly creates a module graph: a list of modules and the relationships between them.

1const imports = {2  "main.js": ["cart.js"],3  "cart.js": ["price.js"],4  "price.js": [],5};6const graph = [];7const todo = ["main.js"];8while (todo.length) {9  const name = todo.shift();10  if (graph.includes(name)) continue;11  graph.push(name);12  todo.push(...(imports[name] ?? []));13}14console.log(graph.join(","));

Line 1 starts with an empty graph. Line 2 puts main.js on the to-do list. Lines 3 through 7 take one module at a time, keep it once, and add its imports. It prints main.js,cart.js,price.js.

1const graph = buildGraph(modules, "main.js");Run2console.log(graph.join(","));

A graph is not necessarily the emitted order. Bundlers parse and link the source first, then choose an order that respects dependencies. That distinction matters when a cycle, a dynamic import, or a side effect appears.

Scope hoisting

After the build understands the graph, it can sometimes place several modules in one JavaScript scope. Scope hoisting is that optimization. It avoids a wrapper function or module lookup for each small module when semantics allow it.

1// before: both files say const price2// const price = 3;3// const price = 5;4 5// after scope hoisting6const price = 3;7const cart_js_price = 5;8console.log(price + cart_js_price);

Lines 2 and 3 cannot both be plain top-level declarations in one scope. The emitted version keeps the first price and renames the second one to cart_js_price. Line 8 therefore prints 8.

This does not mean the tool forgets module behavior. It must preserve imports, exports, evaluation order, and names that can be observed. A bundler can choose wrappers when combining scopes would change behavior.

How tree shaking decides

Tree shaking is build-time removal of code that the bundler can prove is unused and safe to omit. The phrase comes from shaking a tree so unused branches fall away, but the proof is about imports, exports, and effects rather than guessing what a person might click.

1const result = treeShake(modules, "main.js");Run2console.log(result.modules.join(","));

The replay starts at main.js, marks the imported total export, and follows the imports needed to calculate it. A real tool also has to preserve a module whose top level changes global state, registers a custom element, or starts a listener.

1const result = treeShake(modules, "main.js");2console.log(result.modules.join(","));

Change one toggle at a time. When the entry imports nothing, the model keeps only the entry unless price.js says it has side effects. Reset restores the original import of total.

Side effects and package metadata

A side effect is observable work that happens just by evaluating a module, such as changing a global, adding a style rule, or registering code with a host API. An exported function is not itself a side effect until somebody calls it; a top-level call can be.

In a package package.json, the sideEffects field can tell a compatible bundler whether files are safe to drop when no exports are used. A truthful sideEffects: false is a promise about importing files, not a promise that their exported functions do nothing.

import { formatPrice } from "./price.js";
console.log("theme registered");
export { formatPrice };

Line 1 imports a name, but this tiny source does not read it. Line 2 runs as soon as the module evaluates, so a bundler must keep that work. Line 3 only re-exports the imported name. The important question is not whether a line looks unused; it is whether removing evaluation can change what the user sees.

For example, a module may register a custom element, attach a global style, or add a locale. Those jobs can be correct reasons to retain an otherwise unused import. Marking such a file as side-effect-free is a broken promise, and the broken promise can appear only in a production bundle.

// package.json
{
  "sideEffects": false
}

// app.js
import { formatPrice } from "price-tools";
console.log(formatPrice(3));

Line 3 says the package can be treated as pure when an import from it is unused. Line 8 uses formatPrice, so the bundler must still keep the code that creates that export. The metadata does not make the function disappear, and it does not say that calling the function has no effect.

Now change only one fact in your head: remove line 8 and remove the import's only use. A compatible bundler can omit the unused import because the package made that promise. If the package secretly registered a style while evaluating, the promise was false and the missing style is the package author's bug.

Be conservative with metadata. If a stylesheet import or registration module is accidentally marked pure, a production build can remove work your app relied on. Tests should cover the behavior, not only the file size.

Chunk graphs and dynamic imports

A module graph says which source modules depend on which others. A chunk graph groups those modules into output files. Static imports commonly join the initial path; a dynamic import() gives the build a later loading boundary.

async function openSettings() {
  const settings = await import("./settings.js");
  console.log(settings.title);
}

openSettings();

Line 2 does not load settings while the initial graph is evaluated. It asks the runtime for that module when openSettings runs. Line 3 waits for its namespace object and prints its title after the chunk arrives.

const plan = summarizeChunks();
console.log(plan.initial.join(","));
console.log(plan.later.join(","));

Line 1 asks the teaching model for a plan. Line 2 prints the initial group, main.js,cart.js. Line 3 prints the later group, settings.js. This is not a network trace: it only makes the build-time grouping decision visible before a browser runtime fetches anything.

const imports = {
  "main.js": ["cart.js", "settings.js"],
  "cart.js": ["price.js"],
  "price.js": [],
  "settings.js": [],
};
const dynamic = new Set(["settings.js"]);

const plan = planChunkGraph(imports, dynamic, "main.js");
console.log(plan.initial.join(","));
console.log(plan.later.join(","));

Lines 1 through 6 name four source modules. Line 7 labels only settings.js as dynamic. Line 9 calls the graph planner from main.js. The first print is main.js,cart.js,price.js; the second is settings.js.

The planner keeps walking static dependencies in the group it is already building. It switches groups only at the marked dynamic boundary. This is deliberately smaller than a production optimizer, which can share modules between chunks, but it explains why a chunk graph is about delivery groups rather than just source-file order.

A real build can also find a module used by two output groups. It may place that module in a shared chunk, duplicate a very small module, or make another trade-off based on its configuration. Do not infer the final file count from one import(); inspect the emitted plan and then measure the first screen and the later interaction. The graph explains the choice; user-visible loading evidence decides whether that choice helped.

Chunking has a trade-off. Smaller initial chunks can show the first screen sooner, but too many later requests can delay a feature. Read dynamic import and loading performance for the everyday performance decisions.

The runtime and its cache

Output with multiple chunks needs a small runtime. Runtime here means emitted browser code that maps module IDs to factories, remembers evaluated exports, and requests a chunk when a dynamic import needs one.

const cache = new Map();
const require = (name) => cache.get(name) ?? cache.set(name, { name }).get(name);
console.log(require("cart") === require("cart"));

Line 1 creates a cache. Line 2 creates an exports object only when the module is absent, then returns the cached object. Line 3 prints true because both calls receive the same object.

const result = runtimeFactoryModel();
console.log(result.sameExports);
console.log(result.factoryCalls);
console.log(result.cached.join(","));

Line 1 runs the runtime teaching model. Line 2 prints true because both reads share one exports object. Line 3 prints 1: the factory ran once. Line 4 prints cart, the cache key. This is why a runtime cache is about module identity, not merely saving a few characters.

Real emitted runtimes also manage public paths, chunk IDs, loading failures, and asynchronous promises. Their exact generated names differ by tool and configuration, so read them as an implementation detail after learning the three jobs: locate, evaluate once, and load later chunks.

Hot module replacement

Hot module replacement, or HMR, is a development update protocol. After you save a file, the dev server sends the changed module. The runtime replaces it and reruns a nearby accepting callback when one says the update is safe.

if (import.meta.hot) {
  import.meta.hot.accept("./price.js", (changed) => {
    console.log(changed.price);
  });
}

if (module.hot) {
  module.hot.accept("./price.js", () => {
    console.log("price module replaced");
  });
}

Both sketches name price.js as the update boundary. They are intentionally not runnable in the article sandbox because the dev server supplies the hot object. In plain words: change one dish at a buffet without closing the whole restaurant; page state can remain when the changed code is accepted.

HMR cannot safely preserve every update. A changed module may invalidate parents, force a reload, or need framework-specific state recovery. Production visitors receive normal deployed chunks, not a permanent HMR connection.

Practical bundle decisions

Use bundler knowledge to form a small, testable question. Is an unused library export still in the output? Did a dynamic import create a late chunk? Is a side-effectful registration file missing? Inspect the emitted files and a network trace before changing configuration.

Do not split every component automatically. Start with a meaningful boundary such as a settings panel, an editor, or an infrequently opened report. Measure initial loading and the later interaction; a smaller first download is not useful if a common click now waits for too much code.

Prefer a clear import path when output is surprising

import { formatPrice } from "./prices/index.js";
console.log(formatPrice(3));

import { formatPrice } from "./prices/format-price.js";
console.log(formatPrice(3));

Both lines ask for formatPrice. The first path goes through an index file, which may also re-export or evaluate unrelated modules. The second path states the exact module. Modern bundlers can shake many barrels well, but a direct path is easier to inspect when an index file also imports a registration module.

This is a practical before-and-after, not a rule to ban barrels. Keep a barrel when it is a clean public API. Use the bundle report when deciding: if the index file has no effects and exports are statically known, the build may already be optimal.

Common misconceptions

• “Bundling means one file.” A build can emit many chunks.
• “Tree shaking removes every unused-looking line.” It must preserve possible side effects.
• “A dynamic import always improves performance.” It moves work later and can make an interaction wait.
• “HMR is a production cache.” It is a development update mechanism.
• “Scope hoisting is string concatenation.” It must preserve module semantics and rename collisions safely.

Practice exercises

const modules = { "main.js": ["cart.js"], "cart.js": ["price.js"], "price.js": [] };
const seen = new Set();
const visit = (name) => { if (seen.has(name)) return; seen.add(name); modules[name].forEach(visit); };
visit("main.js");
console.log([...seen].join(","));

const cart_js_price = 5;

const dynamicImports = ["settings.js"];
console.log(dynamicImports.length === 1 ? "one async chunk" : "main only");

const cache = new Map();
const require = (name) => cache.get(name) ?? cache.set(name, { name }).get(name);
console.log(require("cart") === require("cart"));

Check your understanding

Answer by separating build-time graph work, browser runtime work, and development-only HMR work.

Key takeaways

• An entry and static imports form the module graph.
• Scope hoisting can combine safe module scopes and rename collisions.
• Tree shaking needs export-use information and truthful side-effect information.
• Dynamic imports help create chunk boundaries that the runtime loads later.
• HMR swaps changed development modules through accepting boundaries when it can.

Coming next: Agents, agent clusters & realms, the specification model for threads, shared memory, and globals.