Module loading in Node.js

A request becomes a module

When Node sees require("cart-utils"), it does not simply open a file with that name. It first decides what kind of request this is, finds one module target, loads and evaluates it if needed, and returns that module's public value. Those steps explain many confusing errors.

Node supports CommonJS and ECMAScript modules (ESM). This lesson follows the Node-specific path around CommonJS require, package files, and loader hooks. The earlier Module loading in browsers lesson explains URL-based browser loading; the published CommonJS and ESM lesson introduces the two module styles.

Keep three questions separate. What text did the code request? Which filename or URL did Node resolve? What object or namespace did the load return? A package name can resolve differently from different folders, and one cache entry is about the resolved filename rather than the text you typed.

The CommonJS wrapper

Every CommonJS file gets a private function-like boundary before its code runs. This is why a top-level const cart in one file does not collide with a top-level const cart in another file. It also explains where CommonJS helper names come from.

1console.log(typeof module);2console.log(typeof exports);3console.log(typeof require);4console.log(typeof __dirname);5console.log(arguments.length);

Line 1 prints object for module. Line 2 prints object for exports. Line 3 prints function for require. Lines 4 and 5 print string and 5. The first four names are values Node supplies, and the final line counts every wrapper argument.

Node documents the wrapper shape as a function receiving exports, require, module, __filename, and __dirname. They look global inside a CommonJS file, but they are local parameters. ESM uses a different model and does not receive this CommonJS wrapper.

1const module = { exports: {} };Run2const exports = module.exports;3const require = (name) => ({ name });4const __filename = "/shop/cart.js";5const __dirname = "/shop";6 7function wrapped(exports, require, module, __filename, __dirname) {8  const cart = { item: "tea" };9  module.exports.item = cart.item;10  return arguments.length;11}12 13console.log(wrapped(exports, require, module, __filename, __dirname));14console.log(module.exports.item);

The require cache

The require cache is the CommonJS loader's object of already loaded modules. After Node resolves and evaluates a file, it normally stores the result under that resolved filename. Another require that resolves to the same filename receives the same module.exports object.

1const first = { cart: ["tea"] };2const second = first;3console.log(first === second);4second.cart.push("milk");5console.log(first.cart.join(","));

Line 1 creates one cart object. Line 2 gives second the same object, so line 3 prints true. Line 4 changes that object through second. Line 5 prints tea,milk through first. A normal cache hit has this same shared-identity idea.

A real CommonJS module can run setup code once, export a service object, and then let later callers share it. This supports cycles too: Node can put a partly initialized exports object in the cache while another module asks for it. Read the in-batch Circular dependencies lesson for that partial-exports case.

You can delete require.cache[require.resolve("./cart")] to make the next require load the file again. That does not update old references held by other modules. Use cache eviction carefully in tests or tooling, not as a normal application refresh button.

How Node resolves a request

Resolution begins with the request text. A request starting with node: names a built-in module. A request beginning with ./, ../, or / is a file path. A bare name like cart-utils is normally a package lookup.

1// Node-only CommonJS file2const cart = require("./cart");3console.log(cart.total);

Line 2 asks for a file relative to the current module. Node's CommonJS rules can try file extensions and older folder entry points, although modern packages should prefer explicit package exports. If the target is not found, Node throws MODULE_NOT_FOUND.

The full algorithm has more branches for package imports, package self-references, file types, and exports. The useful beginner habit is smaller: classify the request first. A missing relative file is not fixed by installing npm packages, and a blocked package subpath is not fixed by adding another ./.

1const paths = lookupPaths("/shop/cart/checkout");Run2const packageFile = resolveExports(exportsField, ["node", "require"]);3console.log(paths[0]);4console.log(packageFile);

Walking node_modules folders

For a bare package request, Node looks beside the requiring module first. If it cannot find the package there, it moves up one directory and tries again. This lets a package use its own nested dependency before it falls back to a parent installation.

1function lookupPaths(fromDir) {2  const pieces = fromDir.split("/").filter(Boolean);3  const paths = [];4  for (let index = pieces.length; index > 0; index -= 1) {5    if (pieces[index - 1] !== "node_modules") {6      paths.push("/" + pieces.slice(0, index).join("/") + "/node_modules");7    }8  }9  return paths;10}11 12console.log(lookupPaths("/shop/cart/checkout").join("\n"));

Line 1 declares a small model, not Node's internal resolver. Line 5 starts at the deepest directory. Line 6 adds a node_modules shelf unless that path segment already has that name. The example prints checkout, cart, and shop shelves in nearest-first order.

The model for /shop/cart/checkout starts with /shop/cart/checkout/node_modules, then /shop/cart/node_modules, then /shop/node_modules. Node's real module object exposes its searched locations as module.paths; the lesson test compares that real array for a nested temporary folder with this same ordered idea.

Package exports and conditions

The exports field is a package's public doorway list in package.json. When it exists, package-name imports can use only the entry points the package declares. This protects internal files from becoming accidental public API.

{
  "exports": {
    "import": "./dist/cart.mjs",
    "require": "./dist/cart.cjs",
    "default": "./dist/cart.js"
  }
}

The first branch is for import and import(). The second is for CommonJS require. The final default branch is a fallback. The Node documentation says object key order matters: write the most specific conditions first and default last.

Conditions can be nested too. A package may first choose a Node-specific branch, then choose import or require inside it. The target is still just one file for one request. Adding an exports field can be a breaking package change because private paths that callers used before become unavailable.

Choose export conditions

The next model uses one exports object with a node branch and nested import, require, and default choices. It is intentionally smaller than Node's real package resolver so you can see the ordered decision.

1const exportsField = {2  node: {3    import: "./dist/cart.mjs",4    require: "./dist/cart.cjs",5    default: "./dist/cart.js",6  },7  default: "./dist/cart.js",8};9 10function resolveExports(field, conditions) {11  for (const [condition, target] of Object.entries(field)) {12    if (condition === "default" || conditions.includes(condition)) {13      return typeof target === "string" ? target : resolveExports(target, conditions);14    }15  }16  return undefined;17}18 19console.log(resolveExports(exportsField, ["node", "require"]));

With node plus require, the model chooses ./dist/cart.cjs. Switch to import and it chooses ./dist/cart.mjs. The selected file changes because the condition list changes, not because the package name changes.

Do not treat conditional exports as a file-extension trick. The condition set is part of resolution. It also means a dual package should test both ways that consumers load it. A file that works with import may expose a different API shape through require.

Module customization hooks

Most applications should use the normal resolver. Advanced tools sometimes need to map a special name, load source from somewhere unusual, or transform a supported source format. Node exposes customization hooks for that boundary.

1// Node-only sketch: hooks.mjs2export async function resolve(specifier, context, nextResolve) {3  if (specifier === "cart-config") {4    return { url: new URL("./cart-config.js", context.parentURL).href, shortCircuit: true };5  }6  return nextResolve(specifier, context);7}8 9export async function load(url, context, nextLoad) {10  return nextLoad(url, context);11}12 13// registerer.mjs14import { register } from "node:module";15register("./hooks.mjs", import.meta.url);

Lines 2 through 7 define resolve. It either returns a custom URL for cart-config or calls nextResolve to preserve ordinary behavior. Lines 9 through 11 define load, which delegates to the next loader in this short sketch. Lines 14 and 15 register the hook module.

Node documents module.register() hooks as asynchronous hooks that run on a separate loader thread. They cannot directly mutate application globals, so communication needs a message channel or other explicit design. Current Node also has synchronous registerHooks(); it is a distinct API with different behavior.

Hooks are powerful enough to make debugging harder. Keep them small, preserve the next hook unless you intentionally short-circuit, and use a build step instead of runtime transforms when that is simpler. The hook is part of loading, before your requested module evaluates.

Using require with ES modules

Modern Node can let CommonJS require() load an ES module when the whole ES module graph is synchronous. The result is the ES module namespace object. That means named exports are properties on the returned value.

1// Node-only CommonJS file2const cart = require("./cart.mjs");3console.log(cart.total);4 5// cart.mjs6export const total = 3;

Line 2 requires cart.mjs. Line 3 prints 3 because line 6 exports total. The returned namespace object is similar to what dynamic import() resolves to, but require() returns it synchronously.

The important limit is top-level await. A module with top-level await, or a dependency graph containing it, needs asynchronous evaluation. Synchronous require cannot wait for it.

1// Node-only CommonJS file2try {3  require("./wait-for-price.mjs");4} catch (error) {5  console.log(error.code);6}7 8// wait-for-price.mjs9await Promise.resolve();10export const price = 3;

Line 3 tries to require the ESM file. Line 5 prints its error code. Lines 9 and 10 make that ESM module asynchronous, so the real Node test proves the output is ERR_REQUIRE_ASYNC_MODULE. Use import() for a module graph that awaits.

Practical debugging habits

When an import fails, do not start by changing random paths. First identify the request form. Then inspect where Node resolved it, whether the package exposes that subpath, and which module is making the request. These three facts normally shrink the problem quickly.

• Use require.resolve() to inspect the filename Node would load.
• Use require.resolve.paths("cart-utils") to inspect bare-package search locations.
• Read the package's exports before importing a deep internal file.
• Check nested dependencies when two callers get different package copies.
• Use import(), not require, when the ESM graph needs top-level await.

Published npm and module resolution lessons cover installing packages and everyday path choices. Here the goal is to inspect the runtime's actual decision before changing code.

Common misconceptions

• “require always runs the file again.” It normally returns a cache entry for the same resolved filename.
• “A package name is the cache key.” Nested callers can resolve the same name to different files.
• “exports lists files for humans.” It is an enforced public entry-point map for package-name loading.
• “A loader hook is ordinary application code.” It participates in resolution and loading before the requested module evaluates.
• “require can handle any ES module.” It cannot synchronously require a graph containing top-level await.

There is one final cache detail worth keeping: a built-in requested with a node: prefix bypasses a same-named cache entry. That is another reason to use node: for built-ins in Node-only code.

Practice exercises

function wrapped(exports, require, module, __filename, __dirname) {
  return arguments.length;
}
console.log(wrapped({}, () => ({}), { exports: {} }, "/shop/cart.js", "/shop"));

console.log(lookupPaths("/shop/cart/checkout")[1]);

console.log(resolveExports(exportsField, ["node", "import"]));

Check your understanding

Answer by separating scope, cache identity, resolution order, exports conditions, and synchronous versus asynchronous loading.

Key takeaways

• CommonJS files run inside a five-argument wrapper, which keeps top-level variables local.
• require.cache normally reuses the exports object for the same resolved filename.
• Node classifies request text, then resolves files or walks node_modules folders for packages.
• Package exports define public entry points and conditional branch order matters.
• module.register hooks customize advanced resolution and loading work on a separate loader thread.
• require can return a synchronous ES module namespace, but top-level await causes ERR_REQUIRE_ASYNC_MODULE.

Coming next: Modules through a bundler, where a build tool creates its own module graph, runtime, chunks, and update system.