Modules, Packages, and Supply-Chain Design

Why it matters

Node.js and Cross-Runtime JavaScript and Types, Documentation, and Package Design covered modules and package exports at an everyday level. Publishing or maintaining a library that other code genuinely depends on needs a deeper model: how circular imports actually resolve, a subtle hazard conditional exports can create, and the reality that every dependency is also a supply-chain trust decision.

Live bindings and module cycles

An ES module import is a live binding — not a one-time copy of a value, but a continuously updated reference to the exporting module’s own binding:

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

// main.js
import { count, increment } from './counter.js';

console.log(count); // 0
increment();
console.log(count); // 1 — the SAME binding, not a stale copy from import time

This is exactly what makes a module cycle (module A imports from B, which imports from A) resolvable in many real cases: because bindings are live rather than copied at import time, a function defined in A can still correctly call something in B even if B was still mid-evaluation when it first imported from A — as long as the actual use of that binding happens later, after both modules finish evaluating, not during the cycle itself.

import() (dynamic import) returns a promise and can run anywhere, including conditionally — useful for genuinely optional dependencies, code-splitting, or breaking an otherwise-necessary cycle. Top-level await in a module delays that module (and anything importing it) until the awaited promise settles — powerful, but it means a slow top-level await in a widely-imported module can silently slow down everything that depends on it.

The dual-package hazard

Recall CommonJS versus ES Modules and conditional exports. When a package ships both a CommonJS and an ESM build, and the same package ends up loaded through both paths in one application (a direct dependency using ESM, a transitive dependency of another package using CommonJS), Node loads two separate module instances — with two separate copies of any module-level state:

// If pkg has: exports: { require: "./dist/cjs.js", import: "./dist/esm.js" }
const cjsVersion = require('pkg'); // one instance, one copy of internal state
import esmVersion from 'pkg'; // a SEPARATE instance, a SEPARATE copy of the same state

cjsVersion.registry.set('a', 1);
console.log(esmVersion.registry.has('a')); // false — genuinely different objects, not a bug in your code

Tree-shaking (a bundler eliminating unused exports from a final bundle) also has real limits: it depends on being able to prove an export is unused, which side-effecting module code (a module-top-level console.log, a global registration) can defeat even when the specific export itself genuinely goes unused.

Designing for library API stability

A library’s exported surface — recall package.json exports — is a promise to every consumer. A compatibility budget is a deliberate policy about how much churn the API will tolerate and how often, communicated up front rather than discovered by consumers via broken builds.

Supply-chain threat modeling

Every dependency is a decision to trust code you (usually) haven’t read, maintained by people you don’t control, that can change at any future npm install. A supply-chain threat model goes beyond “is this specific version’s code good” to account for:

• Provenance: can the published package be verifiably traced back to its claimed source repository and build process, or is it simply trusted on the registry’s word?
• Update risk: does a version range (^2.1.0) allow an automatic update to pull in malicious or compromised code without explicit review?
• Transitive dependencies: a direct dependency’s own dependencies are equally part of the trust surface, often numbering in the hundreds for a modest application.
• Install-time code execution: npm lifecycle scripts (postinstall, and others) run arbitrary code automatically on install — a real, historically-exploited attack vector.

Check your understanding

Practice: warm-up

Given a library’s changelog says a function was removed with no prior deprecation notice in any earlier version, what specifically went wrong from a compatibility-budget perspective — and what should have happened instead?

Practice: apply it

List three concrete things you’d check before adding a new, unfamiliar npm dependency to a production project, beyond just “does it do what I need.”

- Does it (or any of its transitive dependencies) run install-time scripts (postinstall)?
- How large is its own dependency tree, and how actively/by whom is it maintained?
- Does its version range risk pulling in unreviewed changes automatically on the next install,
  and does the project have any automated auditing (npm audit or similar) in place?

Summary

• An ES module import is a live binding, not a copied value — what makes many circular imports resolvable, as long as nothing uses a binding at module top level before the cycle finishes.
• Shipping both CommonJS and ESM builds risks the dual-package hazard: two loaded instances with two separate copies of any module-level mutable state — a design problem in the library, not a bug in consuming code.
• A library’s exported API is a promise; a documented compatibility budget and a deprecate-then- coexist-then-remove path give consumers time to adapt, rather than breaking them abruptly.
• A supply-chain threat model covers more than “is this code good” — provenance, transitive dependency count, update risk, and install-time script execution are all part of the real trust surface a dependency introduces.
• A lockfile guarantees reproducible installs; it says nothing about whether the pinned versions were ever reviewed for malicious content — those are separate concerns.