Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 36 ยท Packages and package.json

How node_modules and Resolution Work

See how Node.js finds a package by walking up node_modules folders, why npm hoists packages, how pnpm uses symlinks, and how to inspect resolution with require.resolve.

When your code says import 'left-pad', Node has to turn that bare name into a file on disk. The rules are simple and fixed, and every package manager arranges node_modules so those rules find the right code. Understanding them explains duplicate packages, "cannot find module" errors and why pnpm looks different.

The lookup rule

For a bare specifier (no ./ or / at the start), Node looks for a folder with that name inside a node_modules directory next to the importing file. If it is not there, Node goes up one folder and tries node_modules there, repeating until it reaches the root of the disk.

TEXT
/project/src/app/main.js   imports "chalk"
  1. /project/src/app/node_modules/chalk
  2. /project/src/node_modules/chalk
  3. /project/node_modules/chalk      <- usually found here
  4. /node_modules/chalk

Within the found folder, Node reads that package's package.json to learn the entry file (exports, then main, then index.js).

Modelling the lookup

This stand-in implements the walk on a fake file system. It uses a set of existing folders, so you can see exactly where the search goes.

Node.js 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.

Notice that lodash is found in the closest node_modules, so a package can carry its own private copy of a library at a different version than the one at the top.

Hoisting and duplicates

Suppose your app needs logger@2 and a dependency of yours needs logger@1. Node can only hold one folder called logger at the top, so the manager puts one version there and nests the other inside the package that needs it:

TEXT
node_modules/
  logger/                 <- version 2 (hoisted, used by your app)
  old-lib/
    node_modules/
      logger/             <- version 1 (nested, used only by old-lib)

Moving shared packages to the top is called hoisting. It avoids storing the same package many times. When versions conflict, only one can be hoisted and the others are duplicated in nested folders. Duplicates are normal, but too many bloat installs; npm ls logger shows every copy.

Node.js A tiny hoisting algorithm

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.

The hoisted result depends on the order packages are visited. That is why a lockfile is needed: it freezes the exact tree so every machine gets the same layout.

pnpm's layout

pnpm does not copy files into your project. Its global store holds each package version once. Inside the project, node_modules contains only symlinks to your declared dependencies, and the real folders live in a hidden node_modules/.pnpm directory where each package sits next to its own dependencies:

TEXT
node_modules/
  chalk -> .pnpm/[email protected]/node_modules/chalk        (symlink)
  .pnpm/
    [email protected]/node_modules/chalk                      (hard-linked from the store)

Node follows symlinks to their real path, so the same lookup rule works, yet your code cannot reach packages you did not declare. That is the strictness you saw in npm, Yarn and pnpm Compared.

Inspecting resolution for real

In Node you can ask where a name resolves with require.resolve, or import.meta.resolve in ES modules. Built-in modules resolve to themselves.

Node.js Asking Node where a module resolves

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.

An unresolved bare name throws ERR_MODULE_NOT_FOUND. In a real project with packages installed, import.meta.resolve('chalk') prints the full file:///.../node_modules/chalk/... URL. For CommonJS the equivalent is require.resolve('chalk').

Common problems

  • Cannot find module 'x': the package is not installed, is installed in a sibling folder, or is a phantom dependency that vanished. Add it to package.json.
  • Two copies of one library: run npm ls <name> (or pnpm why <name>) to see who pulls each version.
  • Huge node_modules: normal; it is rebuildable. Delete it and reinstall when something is corrupted, which solves a surprising number of problems.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How does Node resolve a bare import like 'chalk'?

    Node walks up the directory tree looking for node_modules/chalk.
  2. 2. What is hoisting?

    Hoisting places a package where many dependents can share it.
  3. 3. Why does pnpm prevent phantom dependencies?

    Undeclared packages live in a hidden .pnpm folder and are not reachable by name.
  4. 4. What is the quick fix for a corrupted node_modules?

    node_modules is generated, so reinstalling restores it.

Summary

  • Node resolves bare names by walking up through node_modules folders.
  • The closest match wins, so packages can hold private copies at other versions.
  • Hoisting shares packages; conflicts create nested duplicates; lockfiles freeze the result.
  • pnpm uses a global store plus symlinks, exposing only declared packages.
  • import.meta.resolve and require.resolve show where a name lands.

Next: Entry Points, exports and type