Catch Missing Dependencies Early with pnpm's Strict node_modules Layout

The problem: a dependency your project never declared

You upgrade a package, and the build breaks in a module your code never imported directly. The error says a module cannot be found. This is a phantom dependency: your code required a transitive library that was visible only because a package manager hoisted every dependency into a flat node_modules tree. The package was never in your package.json, so nothing warned you when an upstream change removed it.

pnpm's approach is to make that failure immediate and explicit. Instead of copying every package into one flat directory, pnpm keeps packages in a content-addressable store—a central cache where each package version is stored once, identified by its content hash—and links only your declared dependencies into your project's node_modules. If you try to load a transitive dependency you never declared, Node.js cannot resolve it.

What the default layout looks like

In pnpm's default isolated layout, the top level of node_modules contains symlinks only for the dependencies listed in your manifest. The package files themselves live under node_modules/.pnpm, a virtual store organized by package name and version. Transitive dependencies exist there, but they are not directly reachable from your application code unless you declared them.

Terms used here:

• Content-addressable store: a central cache where packages are stored once by content hash, so multiple projects can share the same files without duplicating them.
• Symlink: a pointer from your project's node_modules to the package in the store.
• Phantom dependency: a transitive package your code imports without declaring it, which works only because a hoisted layout accidentally exposes it.

Worked example: declare express, then try an undeclared transitive package

Create a scratch directory and initialize a project. Run these commands in a terminal with normal user permissions; no administrator access is required.

mkdir scratch-pnpm-demo
cd scratch-pnpm-demo
pnpm init -y
pnpm add express

After installation, inspect the top level of node_modules:

ls -l node_modules

Expected check: you should see a symlink for express, but you should not see transitive libraries as top-level entries. They exist under node_modules/.pnpm instead.

List the virtual store to find a transitive package name:

ls node_modules/.pnpm

Choose one folder name from that output and replace <transitive-dep> below, then try to load it:

node -e "require('<transitive-dep>')"

Expected check: Node.js should throw a module resolution error. That failure is the feature working: your dependency graph is explicit, so an undeclared transitive package cannot resolve at runtime.

Risk: if your code relies on transitive packages, it will break immediately. Treat that as a signal to add the missing declaration to package.json, not as a reason to disable pnpm's isolation.

Because pnpm add express creates package.json, pnpm-lock.yaml, and node_modules, remove the scratch directory when you are done:

cd ..
rm -rf scratch-pnpm-demo

Trade-offs: compatibility versus strictness

The strict layout breaks tools that assume a flat node_modules. Some Jest configurations, older build plugins, and native postinstall scripts resolve peer dependencies by searching upward from their own directory. Under pnpm, those lookups can fail because the expected package is not where a flat-layout tool expects it.

pnpm offers escape hatches such as shamefully-hoist=true or node-linker=hoisted, which flatten the tree for compatibility. Using them reintroduces phantom dependencies, so treat them as temporary bridges while you fix upstream packages, not as permanent defaults. If a package reports a missing peer dependency, first check whether your manifest is missing a declaration before loosening the global setting.

Verify your installed pnpm layout

Exact directory names, configuration keys, and default linkers change between pnpm major versions. Confirm your version before changing settings:

pnpm --version
pnpm config list

Then inspect a real project:

ls -l node_modules
ls node_modules/.pnpm

To check whether the shared store is saving disk space on your filesystem, compare two projects with overlapping dependencies:

du -sh project-a/node_modules
du -sh project-b/node_modules

Disk savings depend on your operating system, filesystem, and store location, so measure locally instead of assuming a fixed reduction.

Closing

pnpm's isolated layout trades some legacy compatibility for a clearer contract: if a package is not in your manifest, your code cannot import it. That catches missing dependencies at install time instead of after an upstream upgrade breaks production. Start a scratch project, confirm that undeclared transitive packages fail to resolve, and only use hoisting escape hatches when a specific tool requires them.