C.W.K.
Stream
Lesson 04 of 05 · published

Content-Addressable Store, Strict node_modules, Workspaces

~11 min · pnpm, concepts, internals

Level 0Newbie
0 XP0/55 lessons0/16 achievements
0/80 XP to next level80 XP to go0% complete

pnpm's three load-bearing concepts are the content-addressable store, the strict nested node_modules, and first-class workspaces. Together they justify the migration from npm.

Content-addressable store. Every package version, identified by SHA256, lives once at ~/.pnpm-store/. When pnpm installs a package into a project's node_modules, it creates a hard link from the project to the store — not a copy. Hard links share inode-level disk; the file is physically the same on disk but reachable from many paths. The result: 50-70% less disk used overall, plus dramatically faster installs because the bytes are already there.

Strict nested node_modules. Each package's dependencies are nested under its own node_modules subfolder, and only packages explicitly declared in package.json are hoisted to the project root. That means your code can only import packages you've declared — no phantom deps. If your code says import x from 'lodash' but you haven't pnpm add lodash'd it, it fails immediately. The strictness is a feature.

Workspaces. pnpm has best-in-class monorepo support. pnpm-workspace.yaml at the repo root declares which sub-packages exist. pnpm install at the root installs deps for all of them, sharing common deps via the store. pnpm -r build runs a script across every workspace package; pnpm --filter web dev runs only in the named package. Combined with the store, large monorepos install dramatically faster than with npm.

Code

A pnpm workspace setup·yaml
# pnpm-workspace.yaml at the repo root
packages:
  - 'apps/*'
  - 'packages/*'

# Then at the root:
pnpm install               # install everything
pnpm -r build              # build every workspace
pnpm --filter web dev      # run 'dev' only in apps/web/
pnpm --filter './apps/*' test  # run tests only in apps/
Verify the strict structure·bash
# After a pnpm install, look at how it's organized
ls node_modules/
# .pnpm/        <- the actual nested deps live here, hard-linked from the store
# react/        <- only top-level, declared deps are hoisted here
# react-dom/
# express/

# A package's transitive deps are NOT visible at the top level — by design.

External links

Exercise

In a pnpm-managed project, look at node_modules/ — find the .pnpm/ subdir and explore its structure. Then in your code, try to import a transitive dep you haven't explicitly declared (e.g. import a sub-dep of a framework). Watch pnpm refuse it. The error message is the lesson.

Progress

Progress is local-only — sign in to sync across devices.
Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)
Sign inPlease sign in to comment.

No comments yet — be the first.