Choosing pnpm’s Package Hoisting Strategy: Strict, Shamefully‑hoist, or Selective

Decision: choose a hoisting mode

When setting up a Node.js project with pnpm you must decide how aggressively pnpm should flatten the node_modules directory. The choice affects disk usage, compatibility with tools that expect a flat layout, and the visibility of version conflicts.

Constraints and goals

• Keep disk consumption low when possible.
• Ensure that build scripts, linters, or IDEs that scan node_modules can find dependencies.
• Avoid hiding mismatched versions of the same package that could cause runtime errors.

Options comparison

Mode	How to enable	Resulting layout	Typical disk impact
Strict hoisting (default)	No extra configuration; pnpm v6+ uses this unless overridden.	Only direct dependencies appear as top‑level folders in node_modules; all other packages are stored in the hidden .pnpm folder.	Lowest – each version is stored once.
Shamefully‑hoist (full flatten)	Set shamefully-hoist=true in .npmrc or run pnpm install --shamefully-hoist.	All dependencies are flattened directly under node_modules, mimicking a classic npm layout.	Higher – duplicate copies may appear when different packages require different versions.
Selective hoisting (pattern‑based)	Add hoist-pattern=* or a specific glob (e.g., hoist-pattern=react*) to .npmrc.	Only packages matching the pattern are flattened; others stay in .pnpm.	Medium – you control which packages are duplicated.

Trade‑offs

• Strict hoisting saves space and makes version mismatches visible (pnpm will warn if two packages need different versions of the same dependency). However, some tools that expect to find a package directly in node_modules (e.g., certain C++ addons, legacy scripts) may fail.
• Shamefully‑hoist maximizes compatibility because every dependency is visible at the top level. The downside is increased disk usage and the risk of silently using a version that differs from what a package declared, which can mask missing peer dependencies.
• Selective hoisting lets you flatten only the packages that cause compatibility problems while keeping the rest strictly hoisted. It requires you to know which packages need flattening and to maintain the pattern over time.

Implementation

1. Open (or create) .npmrc in the root of your project.
2. Add the line that matches the mode you want:

   # For full flattening
   shamefully-hoist=true
   
   # For selective flattening of all packages that start with "lodash"
   # hoist-pattern=lodash*
   
   # To revert to the default strict behavior, either remove the line or set
   # shamefully-hoist=false
   

3. Save the file.
4. Re‑install dependencies to apply the new layout:

   pnpm install
   

5. If you already have a node_modules folder and a lockfile, consider deleting it first to avoid an inconsistent state:

   rm -rf node_modules
   pnpm install
   

Verification and limits

• Check the top‑level contents of node_modules:

  ls node_modules

  Under strict hoisting you should see only your direct dependencies and the hidden .pnpm folder. Under shamefully‑hoist you will see many additional folders corresponding to transitive dependencies.
• Assess disk usage with:

  du -sh node_modules

  Compare the size before and after changing the hoisting setting; shamefully‑hoist usually reports a larger size due to duplicated copies.
• List the top‑level packages pnpm knows about:

  pnpm ls --depth=0

  The output should match what you see flattened in node_modules when shamefully‑hoist is active.
• Limitations: Changing hoisting after a lockfile is generated may leave some packages in the old layout. The safest approach is to remove node_modules and reinstall. Also, shamefully‑hoist can hide missing peer dependencies; after enabling it, run your test suite to catch any runtime issues caused by version mismatches.