What are phantom dependencies and how does pnpm solve this problem?

Phantom Dependencies refer to referencing packages in your project that are not declared in package.json.

Problem Cause:

npm and Yarn use a flat node_modules structure:

bash
# package.json
{
  "dependencies": {
    "express": "^4.18.0"  # express depends on debug
  }
}

# npm/Yarn flat structure
node_modules/
├── express/
├── debug/        # Hoisted up, though not directly declared
└── ...

Dangers of Phantom Dependencies:

javascript
// Can be used directly in code
const debug = require('debug');  // ✅ Works, but dangerous!

// Problems:
// 1. debug not declared in package.json
// 2. express update may no longer depend on debug
// 3. Deleting and reinstalling node_modules may fail
// 4. Other developers cloning project may experience failures

pnpm's Solution:

pnpm uses strict dependency structure to prevent phantom dependencies:

bash
# pnpm structure
node_modules/
├── .pnpm/
│   ├── express@4.18.2/
│   │   └── node_modules/
│   │       ├── express/
│   │       └── debug/      # debug only accessible here
│   └── debug@4.3.4/
└── express -> .pnpm/express@4.18.2/node_modules/express

javascript
// Attempting to access phantom dependency in pnpm
const debug = require('debug');
// ❌ Error: Cannot find module 'debug'

// Must declare explicitly
// package.json
{
  "dependencies": {
    "express": "^4.18.0",
    "debug": "^4.3.4"  // Explicit declaration
  }
}

pnpm Advantages:

1. Clear dependency visibility: Only access dependencies declared in package.json
2. Avoid version conflicts: Different packages can depend on different versions of same package
3. Safer: Prevents accidental use of undeclared dependencies
4. More reliable: Ensures complete dependency relationship recording

Comparison Summary:

Feature	npm/Yarn	pnpm
Dependency Access	Can access all hoisted packages	Only declared dependencies
Dependency Isolation	Weak, flat	Strong, strict isolation
Phantom Dependencies	Easily produced	Completely avoided