Modules

What it is and why it exists

A JavaScript module puts implementation in an independent top-level scope and forms a dependency boundary with explicit imports and exports. An ECMAScript module (ESM) is the format defined by the language standard; CommonJS (CJS) is another format you still maintain in the Node ecosystem. New code generally starts with ESM, but dependencies, build configurations, and older services can still place you at the boundary between both formats.

Modules solve the implicit dependency ordering and shared global namespace of ordinary scripts. Static import statements show what a file needs, while export declarations show which bindings it provides. The runtime can also maintain one instance for each resolved module instead of executing a file for every reference.

A module isn’t just another name for an arbitrary object. export exposes named bindings, while export default exposes a special export named default; importing the whole module produces a module namespace object . It reflects the module’s export set but isn’t a regular configuration object whose properties you can freely add or delete.

You encounter modules in browser <script type="module"> elements, Node applications, npm packages, and bundler entry points. Browsers resolve dependencies from URLs; Node also uses extensions, the nearest package.json, and its type, exports, and imports fields. A bundler may add conveniences such as aliases or extension omission, but those don’t automatically become native browser or Node rules.

Static imports suit dependencies known before startup and let tools build the dependency graph in advance. import() suits loading that genuinely depends on a feature, locale, or route, and it returns a Promise. Both eventually expose the same module namespace semantics; dynamic import isn’t an asynchronous spelling of CommonJS require().

How it works

ESM processing can be understood as resolution, instantiation, and evaluation. The host resolves each module specifier to a module identity, obtains source, and builds a dependency graph; it then connects imports to exports before executing top-level code in dependency order. Implementations can overlap fetch work without changing these observable semantics.

Static import and export declarations can appear only at module top level, so a parser can discover them without running a branch. That static structure supports syntax checks, dependency analysis, and build optimizations, but “statically analyzable” doesn’t mean an export is guaranteed to be tree-shaken. Side effects, re-export style, and the specific builder configuration still affect the artifact.

import() is an expression, so it can appear in a condition, function, or event handler. It resolves the specifier, asynchronously obtains and evaluates the target, then fulfills its Promise with a module namespace object. Resolution and evaluation failures both reject that Promise, so the error boundary must cover await import(...) itself, not only calls made afterward.

Export and import shapes

A named export keeps its exported name, which the importer must match unless it uses as for a local rename. A module has at most one default export, and its importer chooses any local name. import * as catalog gathers every export into a namespace, with the default export at catalog.default.

export { name } from "./source.js" re-exports another module’s binding but doesn’t create a local variable you can use in the current module. export * doesn’t forward the target’s default, and the same name supplied by multiple star exports becomes ambiguous. A public entry point should explicitly list names that can collide or belong to its stable API.

An ESM import is a read-only live binding . If the exporting module rebinds its variable, a static importer reads the new value; the importer can’t assign to that binding itself. By contrast, ordinary object destructuring from a dynamic-import result assigns the property value at that moment to a new local variable, and that local doesn’t keep updating.

Identity, caching, and side effects

The host maintains module instances by resolved module identity. Repeated imports of the same identity generally return the same namespace and share module state; top-level code doesn’t rerun for every importer. Browsers normally identify modules by normalized URL, and Node ESM also caches by URL, where a different query or fragment can create another instance.

That rule enables module-level caches and singleton state, but it also lets top-level side effects affect every importer. It isn’t a business lifecycle manager: tests, requests, or tenants that need isolated state should construct explicit instances. Continuously adding timestamps to specifiers creates new module identities, reruns side effects, and grows the cache.

Module specifiers include relative specifiers, absolute URLs, and bare specifiers. Native browser relative imports normally require complete file extensions, while bare specifiers require an import map or other host configuration. Node resolves packages for bare specifiers and recommends the node: prefix to make built-in modules explicit.

Node 24 format boundaries

In Node 24, .mjs is always ESM and .cjs is always CommonJS. The nearest parent package.json mainly decides how .js is interpreted: "module" means ESM, while "commonjs" or an omitted field normally means CommonJS. Declare type explicitly in each package so tool upgrades or nested package boundaries don’t silently change the interpretation.

CommonJS uses require() and module.exports. exports initially aliases module.exports, so exports.format = format works, whereas exports = { format } only reassigns the local variable and doesn’t replace the real export. Across ESM and CommonJS interop, named-export detection and default-export wrapping depend on the direction and actual module shape; don’t infer them from similar-looking syntax.

Node 24 can use require() to load ESM synchronously when the graph meets its requirements, but a target graph containing top-level await can’t complete synchronously. Dynamic import() from CommonJS provides a more consistent asynchronous boundary. During a migration, verify the real entry point, Node version, and returned shape instead of relying on old slogans that all ESM is impossible to require or that both formats are interchangeable.

The exports field in package.json defines package entry points available to consumers and takes precedence over main when present. A conditional object can choose different targets for import, require, node, or default, with conditions ordered from specific to general. If two paths load independent implementations, the same package can acquire two copies of its state—the dual-package risk that calls for identity and side-effect-count tests.

Examples

All four examples use data: modules so one file runs independently in Node 24 and ESM-capable browsers. Production code normally imports real URLs or package names; source is inline here only to keep every example copyable and executable while demonstrating exact module semantics.

Read named and default exports

The module namespace contains default, total, and vatRate. Namespace keys are sorted as strings, so the output can show the complete export shape deterministically.

Object.keys() includes default because a default export isn’t a second channel outside the namespace object. With real files, the static form could be import catalogName, { total } from "./catalog.js"; catalogName is locally chosen, while total must match the exported name.

An exported object can still have its internal properties changed by a caller. “The import binding is read-only” only prevents redirecting the imported name to another value; it doesn’t freeze an array or object referenced by that name. A module API that promises immutability must separately control exposed references and update operations.

Distinguish a live property from a destructured snapshot

stock.available reads a live export through the namespace. The destructured local available is just the number 2, so it stays unchanged after reserve() runs.

const stockSource = `
export let available = 2;
export function reserve() {
  available -= 1;
}
`;

const stockUrl = `data:text/javascript,${encodeURIComponent(stockSource)}`;
const stock = await import(stockUrl);
const { available } = stock;

console.log(stock.available, available);
stock.reserve();
console.log(stock.available, available);

2 2
1 2

If this used static import { available } from "./stock.js", available itself would be a live binding and its second read would produce 1. This difference often appears when static code is refactored to await import(): immediate destructuring looks similar but can freeze the reference that was meant to stay live.

Live bindings propagate rebinding; they aren’t deep change notifications. If a module exports an object and the importer still holds that object, property mutations are naturally visible because the object identity is shared, not because the module system watches every property.

Constrain dynamic import with an allowlist

A fixed table resolves public locale keys to trusted URLs. An unknown key is rejected before module resolution begins, so the caller can distinguish an unsupported locale from a failure while evaluating the module itself.

const localeSources = {
  en: `export default { checkout: "Checkout" };`,
  zh: `export default { checkout: "结算" };`,
};

const localeUrls = Object.fromEntries(
  Object.entries(localeSources).map(([key, source]) => [
    key,
    `data:text/javascript,${encodeURIComponent(source)}`,
  ]),
);

async function loadLocale(language) {
  const url = localeUrls[language];
  if (!url) throw new RangeError(`Unsupported locale: ${language}`);
  return (await import(url)).default;
}

console.log((await loadLocale("en")).checkout);
console.log((await loadLocale("zh")).checkout);

try {
  await loadLocale("ja");
} catch (error) {
  console.log(`${error.name}: ${error.message}`);
}

Checkout
结算
RangeError: Unsupported locale: ja

Putting a request parameter directly into import() gives outside input control over module selection and makes it hard for a bundler to determine which files belong in the artifact. The allowlist puts public keys, actual specifiers, and authorization policy in one place. A build step can generate a large table, but runtime selection should still be a lookup rather than an arbitrary path fragment.

This catch surrounds only the call that is expected to fail. Application code must also decide whether module download failure, syntax failure, and initialization failure allow fallback; returning an empty object for every case disguises deployment faults as “locale missing.”

Observe module identity and caching

Two imports of the same data: URL share one module instance, so its top-level log appears once. Adding a fragment creates a distinct identity, evaluates the module again, and produces another marker object.

const moduleSource = `
console.log("module evaluated");
export const marker = {};
`;

const moduleUrl = `data:text/javascript,${encodeURIComponent(moduleSource)}`;
const first = await import(moduleUrl);
const second = await import(moduleUrl);
const distinct = await import(`${moduleUrl}#copy`);

console.log(`same URL: ${first.marker === second.marker}`);
console.log(`different URL: ${first.marker === distinct.marker}`);

module evaluated
module evaluated
same URL: true
different URL: false

Don’t treat a query or fragment as a general-purpose “reload module” API. Different hosts and tools can further transform specifiers, and every new identity may retain another copy of state. Development servers have their own hot-update lifecycle protocols; application code shouldn’t imitate them with random cache busters.

To test a shared instance, prefer public behavior such as initialization counts or returned object identity. If the requirement is isolated state, put it behind a factory and let each test create an instance explicitly instead of trying to clear an internal ESM cache.

Pitfalls

Treating bundler rules as host rules

Guessing default and named exports

Giving outside input a dynamic specifier

Reading uninitialized bindings in a cycle

Ignoring the owner of module state

Mismatching Node file formats

Further reading

• MDN: JavaScript modules guide
• MDN: static import declaration
• MDN: dynamic import() operator
• Node.js 24: ECMAScript modules
• Node.js 24: packages and module types