|$ curl https://forge-ai.dev/api/markdown?path=docs/npm/pnpm

$cat docs/pnpm-deep-dive.md

updated Today·24-32 min read·published

pnpm Deep Dive

◆pnpm◆Monorepo◆Store◆Intermediate🎯Free Tools

Introduction

pnpm (performant npm) stores every package version once in a content-addressable global store and hard-links files into project node_modules. The on-disk layout is a non-flat, symlink-based structure that prevents accessing undeclared dependencies — the opposite of npm's permissive hoist.

That combination — disk efficiency + strictness + excellent workspace filtering — is why pnpm wins most large monorepos. See the comparison matrix on npm vs Yarn vs pnpm vs Bun.

📝

note

Install pnpm via Corepack and pin "packageManager": "pnpm@…" so every machine uses the same major.

How / Why / Requirements

Question	Answer
Why pnpm?	Shared store, hard links, strict deps, fastest practical monorepo workflows, catalogs
How?	Corepack enable → set packageManager → pnpm install → commit pnpm-lock.yaml
Requirements	Filesystem that supports hard links (local disk; some network FS break); Node + Corepack
When not?	Broken tools that need flat hoist and you cannot use shamefully-hoist / public-hoist-pattern

Content-Addressable Store

Each package tarball is unpacked into the store keyed by content hash. Projects never duplicate package bytes for the same version — they hard-link into node_modules/.pnpm and symlink package names into place.

store.sh

Bash

1	pnpm store path # where the global store lives
2	pnpm store status # verify integrity / modified packages
3	pnpm store prune # remove unreferenced packages
4
5	# Optional: relocate store (CI cache mounts)
6	pnpm config set store-dir /var/cache/pnpm-store

ℹ

info

In CI, cache the store directory keyed by lockfile hash. Combined with --frozen-lockfile, installs become mostly hard-link operations.

Hard Links & Layout

Hard links share inodes with the store. Editing a file under node_modules can mutate the store copy — avoid manual edits; use pnpm patch instead.

inspect-layout.sh

Bash

1	ls node_modules # only direct deps + .pnpm + .bin
2	ls node_modules/.pnpm \| head # virtual store with versioned folders
3	readlink node_modules/lodash # symlink into .pnpm/.../node_modules/lodash

Path	Role
node_modules/.pnpm	Virtual store; real package files via hard links
node_modules/<name>	Symlink to declared dependency only
~/.local/share/pnpm/store	Typical global store location (OS-dependent)

Peer Dependency Strictness

pnpm is strict about peers. Missing or mismatched peer dependencies produce errors (not quiet hoisting). That forces correct package.json declarations — valuable in monorepos.

.npmrc

INI

1	# Default is strict; relax only when migrating legacy trees
2	auto-install-peers=true
3	strict-peer-dependencies=true
4	# Temporary escape during migration:
5	# strict-peer-dependencies=false

⚠

warning

Turning off strict peers hides real bugs. Prefer adding peers / using pnpm.peerDependencyRules for known false positives.

shamefully-hoist & Hoist Patterns

Some tools (older ESLint plugin resolvers, frameworks expecting flat trees) break under isolation. pnpm offers controlled hoisting escapes.

.npmrc

INI

1	# Nuclear option — hoist everything (loses isolation)
2	shamefully-hoist=true
3
4	# Prefer targeted patterns:
5	public-hoist-pattern[]=types
6	public-hoist-pattern[]=eslint
7	public-hoist-pattern[]=prettier
8	hoist-pattern[]=*

Setting	When	Cost
shamefully-hoist	Legacy toolchain demands flat tree	Phantom deps return
public-hoist-pattern	Hoist specific packages to root	Limited leakage
packageExtensions / deps	Missing peer/dep declarations	Best long-term fix

✓

best practice

Start strict. Add hoist patterns only for packages that fail. Revisit after major upgrades — many tools no longer need shameful hoisting.

.npmrc for pnpm

pnpm reads .npmrc (and pnpm-workspace.yaml for workspace + catalogs). Commit project-level settings; keep auth tokens in user-level or CI secrets.

.npmrc

INI

1	engine-strict=true
2	auto-install-peers=true
3	strict-peer-dependencies=true
4	shamefully-hoist=false
5	# registry overrides for scopes
6	@acme:registry=https://npm.pkg.github.com
7	//npm.pkg.github.com/:_authToken=${NPM_TOKEN}

pnpm-workspace.yaml

YAML

1	packages:
2	- "apps/*"
3	- "packages/*"
4	- "!/test/"
5	- "!packages/deprecated"

filter.sh

Bash

1	pnpm --filter @acme/web build
2	pnpm --filter "./packages/**" test
3	pnpm --filter "...@acme/web" build # web + dependencies
4	pnpm --filter "@acme/web..." test # web + dependents
5	pnpm -r run lint # recursive all packages
6	pnpm --filter @acme/web add zod

🔥

pro tip

Filter syntax with ... (dependents/dependencies) is the killer feature for large monorepos — run only the affected subgraph in CI.

Catalogs

Catalogs centralize dependency versions for the whole workspace. Packages reference catalog: instead of repeating version strings.

pnpm-workspace.yaml

YAML

1	packages:
2	- "packages/*"
3	catalog:
4	react: ^19.0.0
5	typescript: ^5.7.0
6	zod: ^3.24.0

packages/ui/package.json

JSON

1	{
2	"name": "@acme/ui",
3	"dependencies": {
4	"react": "catalog:",
5	"zod": "catalog:"
6	},
7	"devDependencies": {
8	"typescript": "catalog:"
9	}
10	}

ℹ

info

Catalogs replace many uses of Yarn constraints for "one React version" policies with a simpler shared version table.

Overrides

Force a transitive dependency version for security patches or broken ranges. In pnpm this lives under pnpm.overrides in the root package.json.

package.json

JSON

1	{
2	"pnpm": {
3	"overrides": {
4	"lodash": "4.17.21",
5	"foo>bar": "2.0.0"
6	},
7	"peerDependencyRules": {
8	"allowedVersions": {
9	"react": "19"
10	},
11	"ignoreMissing": ["@types/react"]
12	}
13	}
14	}

pnpm patch

patch.sh

Bash

1	pnpm patch some-pkg@1.2.3
2	# edit the printed temporary folder
3	pnpm patch-commit /tmp/path-to-edit
4	# records patch under patches/ and package.json pnpm.patchedDependencies

📝

note

Prefer upstream PRs. Keep patches tiny and re-verify on every upgrade.

pnpm dlx & exec

dlx.sh

Bash

1	pnpm dlx create-vite@latest
2	pnpm dlx cowsay "strict by default"
3	pnpm exec tsc --noEmit # local binary
4	pnpm create vite my-app # create-* shortcut

Why pnpm Wins Monorepos

Advantage	Detail
Disk	One store for all packages and all checkouts
Strictness	No accidental cross-package phantom imports
Filtering	Powerful --filter graph queries for CI
Catalogs	Central versions without custom constraint DSLs
Compatibility	Still provides node_modules (unlike default PnP)

ci-monorepo.sh

Bash

1	pnpm install --frozen-lockfile
2	pnpm --filter "...[origin/main]" run test
3	# run tests for packages changed since main, plus dependents

Migrating from npm

migrate.sh

Bash

1	corepack enable
2	corepack prepare pnpm@9.15.0 --activate
3	pnpm import # convert package-lock.json
4	rm package-lock.json
5	pnpm install
6	# fix missing deps that npm hoisting hid
7	pnpm why <pkg>
8	# add undeclared imports as real dependencies
9	npm pkg set packageManager=pnpm@9.15.0
10	npm pkg set scripts.preinstall="npx only-allow pnpm"

Symptom after migrate	Cause	Fix
Cannot find module X	Phantom dep	pnpm add X in the right package
ESLint plugin resolve fail	Needs hoist	public-hoist-pattern for eslint*
Peer dependency errors	Strict peers	Install peers or peerDependencyRules

Essential Commands

Command	Purpose
pnpm install --frozen-lockfile	CI install; fail on drift
pnpm add / add -D	Add runtime / dev deps
pnpm update --latest	Bump within policy
pnpm outdated	List available updates
pnpm audit	Security advisories
pnpm deploy <dir>	Deployable subset from workspace

Adoption Checklist

Pin pnpm with Corepack packageManager
Commit pnpm-lock.yaml and workspace config
Use --frozen-lockfile in CI
Cache the store directory
Introduce catalogs for shared libs
Prefer filters over running everything always
Document hoist escapes in README
Block other managers with only-allow

Community

Get help on Slack, Discord or VIP

Stuck on a guide? Join the community and ask.

Join Slack Join Discord Kaundal VIP

X GitHub YouTube Instagram Facebook Discord Slack Telegram Buy me a coffee Ko-fi Sponsor