Modules and Bundling

CommonJS builds its exports at runtime: require is an ordinary function call and module.exports is a mutable object whose properties can be added conditionally and read with computed keys. The export set is not knowable before execution, so tools keep the whole module.

Map the import graph and look for a loop — a tool such as madge run with --circular, or ESLint's import/no-cycle rule, lists them mechanically. Then break the loop by extracting the shared code into a third module, or by inverting the dependency, rather than by reordering imports.

require() runs a module's body to completion synchronously before returning, so anything at a module's top level executes during the require call and blocks the single thread. Move expensive work into exported init or factory functions the application calls deliberately.

Two builds of the same library are loaded, so two distinct ValidationError constructors exist. The error came from one copy and is being tested against the other copy's class, and instanceof compares prototype identity, not names. Confirm it by comparing the file paths each side actually resolved.

Guarantee a single implementation. Either ship one build and make the other entry a thin wrapper that re-exports it, move all stateful pieces into one internal file both builds load, or publish a single format. Each trades bundle quality or consumer convenience for guaranteed single-instance state.

import() reports failure by rejecting its promise — nothing is thrown at the call site. Wrap the await in try/catch, distinguish a failed fetch from an error thrown while the module evaluates, show a real error state, and recover from a stale-deploy 404 with a full page reload rather than a bare retry.

Named exports keep the public name under the author's control, so identifiers stay consistent, greppable and safely renameable by tooling. A default export makes a one-artifact file read cleanly but hands the naming decision to every importer, which invites drift.

An ES module import is a live binding to the exporter's variable, while destructuring a CommonJS require copies the property's value at that instant. Export a function or a state object so consumers read the value at access time instead of capturing it.

Two module rules bit at once. Module scope means the other file's helper is no longer visible as a bare name, so it must be exported and imported; implicit strict mode turns the undeclared assignment from a silent global into a ReferenceError, so declare it with const or let.

Once. A module's body is evaluated exactly one time per instance, and instances are keyed by the resolved location of the module, so all five importers share one instance. Two instances appear when the same source resolves to two different locations — a duplicated package copy, a differing specifier, or a separate realm.

Named exports from a CommonJS module are discovered by statically scanning its source before it runs, so properties attached dynamically are invisible to the linker even though they exist at runtime. Default-import the module and destructure the property afterwards.

Nothing happens: the graph's evaluation promise never settles, so the modules stay half-evaluated and the entry point never runs. There is no error, no stack trace and no timeout — the load simply hangs, which is why it is diagnosed by tracing where logging stops.

It claims that no file in the package does anything observable merely by being evaluated, so a bundler may skip importing any module whose exports go unused. It is an unverified promise; a false one silently deletes polyfills, styles and registrations from production builds.

Good boundaries sit where a module is both large and genuinely optional, gated behind a user intention the app can anticipate. Over-splitting fragments code into many small units, creates sequential request waterfalls when one lazy module lazily imports another, and shifts latency onto interactions.

Use top-level await when a module's export is meaningless until an async step completes and every consumer needs it — it makes correct ordering structural. Prefer an exported initializer or promise when the module is widely imported, when the work can fail or needs retry control, or when consumers must load synchronously.

ns is a module namespace object: non-extensible, with one non-configurable property per export whose value is a live view of the exporter's variable. Adding, deleting or overwriting properties is rejected, and its prototype is null.

It asserts that the immediately following call has no observable effects, so if its result is unused the whole call may be deleted. Minifiers and bundlers read it. Nothing verifies it, so a wrong annotation silently removes real behaviour from production builds.

Decide by what your public API depends on. If correctness rests on shared state or class identity, ship a single implementation so two copies are impossible. If the library is stateless, dual builds are a bundle-size convenience with no correctness risk, and the choice becomes purely a compatibility question.

Treat evaluation-order dependence as hidden coupling: the ordering contract lives in import statements no reviewer reads as ordering. Prefer module bodies that only declare things, plus one composition root that constructs and wires everything in an order you can read, test, and change.