Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Module Systems

Node.js module resolution algorithm

How Node.js turns a require() or import specifier into a file: built-ins, relative paths, node_modules lookup, extensions, index files and the differences between CJS and ESM.

Every require('x') and import 'x' starts with a specifier, a string. Module resolution is the process that turns it into the one file that Node.js will load. The rules are different for CommonJS and for ES modules, and understanding them explains most "Cannot find module" errors.

In short: a specifier is either a built-in (node:fs), a path (starts with ./, ../ or /), a # import (see package.json imports), or a bare name such as express or lodash/fp, which is looked up in node_modules folders.

NODE
require.resolve('./util');        // CommonJS: a path with guessed extension
import.meta.resolve('./util.js'); // ESM: the full file URL, no guessing

Try it

Node.js Bare names walk up node_modules

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js ES modules do not guess

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

How it works

1. Built-in modules

A name that matches a core module (fs, node:fs, node:test) is returned immediately, before any file lookup. Some modules exist only with the node: prefix. A built-in always wins over a package with the same name, so a package called fs in node_modules is never loaded by require('fs').

2. Relative and absolute paths

For CommonJS, Node.js tries the exact file, then adds .js, .json and .node, then looks for a directory with a package.json main field, then for index.js, index.json and index.node. For ES modules the specifier must be the full file name with extension, and a directory is not accepted (ERR_UNSUPPORTED_DIR_IMPORT). A missing file gives ERR_MODULE_NOT_FOUND in ESM and MODULE_NOT_FOUND in CommonJS.

3. Bare names and node_modules

For require('colors') from /a/b/c/file.js, Node.js checks /a/b/c/node_modules/colors, then /a/b/node_modules/colors, then /a/node_modules/colors, then /node_modules/colors, and finally the global folders listed in NODE_PATH, $HOME/.node_modules and $PREFIX/lib/node. The first match wins. When it finds a package folder it reads package.json: the exports field if present (see package.json exports), else main, else index.js.

4. Differences between CommonJS and ESM

CommonJS require() ES module import
Extension guessing Yes (.js, .json, .node) No
Directory index Yes No
exports of a package Honored Honored
Relative to The requiring file The importing file's URL
Result of a lookup A path A file: URL
Cache require.cache by file path Module map by URL
Symlinks Resolved to real paths by default Resolved to real paths by default

Usage notes

  • Use the tools. require.resolve() and import.meta.resolve() show what a specifier turns into without running the file. Printing these values is the quickest way to debug a lookup.
  • ERR_MODULE_NOT_FOUND often just means a missing extension in ESM: write ./util.js, not ./util.
  • exports hides files. Once a package has exports, any path not listed throws ERR_PACKAGE_PATH_NOT_EXPORTED, even if the file exists.
  • Case matters on Linux, not on default Windows or macOS volumes. A require that works on a laptop can fail in a container.
  • Symlinks: a package linked with npm link or a workspace is resolved from its real location, so its own dependencies are searched from there. --preserve-symlinks changes this.
  • TypeScript with moduleResolution: "nodenext" follows the same rules, which is why imports there must include .js extensions.
  • Speed. Resolution results are cached, but a deep tree of node_modules folders means several failed file-system checks per bare import.