CommonJS Module Semantics

## require is a function, not a declaration CommonJS is the module system Node adopted before ECMAScript had one of its own; it is not part of the ECMAScript language specification. Inside a CommonJS file you get three names to work with: `require`, `module`, and `exports`. The most important consequence of `require` being a plain function is that it has no special syntactic position and no separate pre-pass. It can sit at the top of a file, inside an `if`, inside a function body, or in the middle of an expression, and it does its work at the moment control reaches it. ```js // main.js console.log('before'); const cfg = require('./config'); // config.js runs here, right now console.log('after', cfg.port); ``` That is already a meaningful difference from a declarative import form, where the loading is part of the module's static structure rather than a statement that executes in order. ## The module object and its exports Before a module's body runs, the host creates a `module` object for that file whose `exports` property is initialised to a fresh empty object, and a local variable `exports` initialised to that same object. The body then either attaches properties to it or replaces `module.exports` outright. When the body finishes, the value currently stored in `module.exports` is exactly what `require` returns to the caller. That is the whole contract: *whatever `module.exports` points at when the body ends*. A file that never touches its exports still returns something — the empty object it was seeded with: ```js // side-effect-only.js globalThis.installed = true; // main.js const m = require('./side-effect-only'); console.log(m); // {} — the seeded object, not undefined ``` That is why `require('./x').doThing()` on a module that forgot to export throws `TypeError: ... is not a function` rather than a "module not found" style error: you got an object, just an empty one. ## Synchronous, run-to-completion loading The load is synchronous and runs the module body to completion. Nothing else in the program interleaves with it. If the required module itself requires other modules, those calls happen inside its body, so loading proceeds depth-first, and each nested body finishes before the `require` that triggered it returns. ```js // a.js console.log('a start'); require('./b'); console.log('a end'); // b.js console.log('b'); ``` Requiring `a.js` prints `a start`, `b`, `a end`. The ordering is entirely explained by ordinary synchronous function-call semantics — there is no queue, no callback, no promise involved. This is also why you cannot `await require(...)` meaningfully: `require` does not return a promise, so awaiting it just wraps an already-available value. ## Returned by reference, not copied The caller and the module end up holding the same object. If the module later mutates a property on the object it exported, holders see the change, because there is one object. What does *not* propagate is a later reassignment of `module.exports` itself: a caller that already captured the old object keeps pointing at the old object, since it holds a reference to a value, not a live view of the module's `module.exports` slot. ```js // late.js module.exports = { ready: false }; setTimeout(() => { module.exports = { ready: true }; }, 0); // a caller that already required this file still sees { ready: false } ``` The practical rule that falls out: if a module needs to publish something that changes over time, mutate a property on the exported object or expose a function, rather than swapping the exports object out from under everyone. ## When loading throws A module body is just code, so it can throw. The exception travels out of the `require()` call to the requiring module's stack frame, and can be caught: ```js try { const plugin = require('./optional-plugin'); } catch (err) { // the module body threw, or the file could not be loaded } ``` Because the failure is synchronous, there is no rejected promise and no unhandled-rejection warning involved. ## Interview traps to be ready for The common wrong answers are that `require` returns a promise, that it schedules loading in the background, or that the returned value is some special namespace wrapper. All three are the same misunderstanding: `require` is a normal, blocking function call that returns an ordinary JavaScript value. The second trap is expecting `require` to hoist. It does not; a `require` placed inside a function body simply does not run until that function is called, which is the entire basis of the lazy-require idiom.