The module resolution algorithm: how Node finds your code

Three kinds of specifier, and the fork they trigger

Before Node looks at a single byte on disk, it classifies the specifier — the string you passed to require() or import — into one of three kinds, because each takes a different path through the algorithm:

• Relative — starts with ./, ../, or /. require("./utils"). Resolved against the directory of the importing file.
• Bare (a.k.a. “package”) — a name with no leading dot or slash. require("express"), import "lodash/fp". Triggers the node_modules lookup walk.
• Absolute / URL — a full filesystem path, or under ESM a file: / node: / data: URL. import "node:fs".

require("./parser");      // relative → resolve next to the current file
require("parser");        // bare → search node_modules up the tree
require("/opt/app/p.js"); // absolute → use the path directly

This first decision is the one people skip. "./utils" and "utils" look almost identical but route through completely different machinery: the first never touches node_modules, the second never looks next to your file. A leading ./ you forgot — or one you added by accident — sends resolution down the wrong branch entirely.

CJS: probe file, then directory, then index

For a relative specifier in CommonJS, Node takes the path and tries, in strict order, until one hits:

1. As an exact file. LOAD_AS_FILE(X): try X literally, then X.js, then X.json, then X.node (a compiled addon). This is extension probing — require("./utils") quietly becomes ./utils.js. The order is fixed: a sibling utils.js always wins over utils.json.
2. As a directory. If X is a directory, LOAD_AS_DIRECTORY(X): read X/package.json and follow its main field (resolved again as a file); if there is no package.json or no main, fall back to X/index.js, then X/index.json, then X/index.node.
3. Fail. If neither works, throw MODULE_NOT_FOUND.

// require("./shapes") tries, in order:
//   ./shapes            (exact file — usually absent)
//   ./shapes.js
//   ./shapes.json
//   ./shapes.node
//   ./shapes/           → its package.json "main", else ./shapes/index.js …

Two takeaways for the Cannot find module './utils' mystery. First, CJS does not resolve .ts — require only knows .js/.json/.node, so a bare ./utils pointing at utils.ts fails unless a loader (ts-node, tsx, a bundler) taught Node that extension. Second, a folder “just works” only because of the index.js fallback; delete the index and the same require("./shapes") breaks even though the directory still exists.

The node_modules walk: bare specifiers climb the tree

A bare specifier triggers the most distinctive part of the algorithm: NODE_MODULES_PATHS. Node does not have one global library directory. Instead, starting from the importing file’s directory, it looks for ./node_modules/<pkg>, and if that is absent it goes up one directory and tries again, repeating until it reaches the filesystem root.

import in /app/src/api/handler.js  →  require("lodash")
  search /app/src/api/node_modules/lodash
  search /app/src/node_modules/lodash
  search /app/node_modules/lodash      ← found here
  search /node_modules/lodash          (only if still missing)

Once it finds the lodash directory, it resolves inside it with the same file/directory/index logic (honouring that package’s package.json main or exports). This upward walk is exactly why a dependency installed at the project root is visible to deeply nested files, and why two copies of a library at different depths can coexist — each importer resolves to the nearest one. It is also why MODULE_NOT_FOUND on a bare name almost always means “not installed at or above this path,” not “typo in the filename.”

ESM resolution: URLs, mandatory extensions, no index

ESM runs a different algorithm, and the differences are exactly where the cross-environment failures live. ESM resolves everything to a URL (usually file:), and that reframing changes the rules:

• Extensions are mandatory. import "./utils.js" works; import "./utils" throws ERR_MODULE_NOT_FOUND. There is no extension probing and no directory index.js fallback for relative specifiers — you write the full path or it fails. (This is the single most common surprise migrating CJS code to ESM.)
• Bare specifiers still use the node_modules walk, but the package’s entry point is chosen by its exports / main field, and subpaths must be explicitly exported (the next lesson).
• node: is explicit. Built-ins resolve via the node: scheme (import "node:fs"); the bare form import "fs" still works for built-ins but node: is unambiguous and the modern default.

import { readFile } from "node:fs/promises"; // built-in, explicit scheme
import { parse } from "./parser.js";          // extension REQUIRED
import express from "express";                // bare → node_modules walk + exports
// import { parse } from "./parser";          // ✗ ERR_MODULE_NOT_FOUND under ESM

The package.json fields that steer resolution

Three package.json fields decide how a package (a bare import) resolves, and they form a precedence chain:

• "type" — "module" makes .js files in that package ESM; "commonjs" or absent makes them CJS. This governs how the resolved file is interpreted, not where it is found.
• "main" — the legacy entry point: the file a bare require("pkg")/import "pkg" resolves to when exports is absent. "main": "./lib/index.js".
• "exports" — the modern entry map. When present, it overrides main and becomes authoritative: it can route import and require to different files and, crucially, it blocks any path not listed (covered fully next lesson). "module" is a non-standard bundler-only field — Node ignores it.

The precedence is the gotcha: if a package ships an exports field, main is ignored by Node, and a deep import like require("pkg/lib/internal") that worked for years can suddenly throw ERR_PACKAGE_PATH_NOT_EXPORTED after the package adds exports. The file still exists; the resolver now refuses to look at it.