/pnpm

pnpm Performance Optimization

pnpm is fast by default, but these optimizations can make it even faster.

Install Optimizations

Use Frozen Lockfile

Skip resolution when lockfile exists:

pnpm install --frozen-lockfile

This is faster because pnpm skips the resolution phase entirely.

Prefer Offline Mode

Use cached packages when available:

pnpm install --prefer-offline

Skip Optional Dependencies

If you don't need optional deps:

pnpm install --no-optional

Skip Scripts

For CI or when scripts aren't needed:

pnpm install --ignore-scripts

Caution: Some packages require postinstall scripts to work correctly.

Only Build Specific Dependencies

Build-script approval is a single allowBuilds map (replaces onlyBuiltDependencies/neverBuiltDependencies). Only allowed packages run install scripts:

allowBuilds:
  esbuild: true
  '@swc/core': true
  core-js: false      # explicitly skip

Packages not listed are treated as unreviewed (blocked by default). See features-supply-chain-security for the full build-approval workflow.

Store Optimizations

Side Effects Cache

Cache native module build results (enabled by default):

sideEffectsCache: true

This caches the results of postinstall scripts, speeding up subsequent installs.

Global Virtual Store

For many checkouts of the same repo (e.g. git worktrees / multiple agents), enable the global virtual store so each project's node_modules is just symlinks into one shared store — near-zero per-checkout cost. Auto-disabled in CI.

virtualStoreType: global

Shared Store

A single content-addressable store is used for all projects by default:

storeDir: ~/.local/share/pnpm/store

Benefits: packages downloaded once, hard links save disk space, faster cached installs.

Store Maintenance

Periodically clean unused packages:

# Remove unreferenced packages
pnpm store prune

# Check store integrity
pnpm store status

Workspace Optimizations

Parallel Execution

Run workspace scripts in parallel:

pnpm -r --parallel run build

Control concurrency:

workspaceConcurrency: 8

Stream Output

See output in real-time:

pnpm -r --stream run build

Filter to Changed Packages

Only build what changed:

# Build packages changed since main branch
pnpm --filter "...[origin/main]" run build

Topological Order

Build dependencies before dependents:

pnpm -r run build
# Automatically runs in topological order

For explicit sequential builds:

pnpm -r --workspace-concurrency=1 run build

Network Optimizations

Network/registry settings are camelCase in pnpm-workspace.yaml (registry URLs may also go in registries):

registries:
  default: https://registry.npmmirror.com/
fetchRetries: 3
fetchRetryMintimeout: 10000
fetchRetryMaxtimeout: 60000
networkConcurrency: 16          # auto: clamp(workers x 3, 16, 64)
httpProxy: http://proxy.company.com:8080
httpsProxy: http://proxy.company.com:8080

Lockfile Optimization

Single Lockfile (Monorepos)

Use shared lockfile for all packages (default):

sharedWorkspaceLockfile: true

Benefits:

• Single source of truth
• Faster resolution
• Consistent versions across workspace

Lockfile-only Mode

Only update lockfile without installing:

pnpm install --lockfile-only

Benchmarking

Compare Install Times

# Clean install
rm -rf node_modules pnpm-lock.yaml
time pnpm install

# Cached install (with lockfile)
rm -rf node_modules
time pnpm install --frozen-lockfile

# With store cache
time pnpm install --frozen-lockfile --prefer-offline

Profile Resolution

Debug slow installs:

# Verbose logging
pnpm install --reporter=append-only

# Debug mode
DEBUG=pnpm:* pnpm install

Configuration Summary

Optimized pnpm-workspace.yaml for performance:

# Install behavior
autoInstallPeers: true
sideEffectsCache: true
optimisticRepeatInstall: true

# Build approval (only what's necessary)
allowBuilds:
  esbuild: true
  '@swc/core': true

# Network
fetchRetries: 3
networkConcurrency: 16

# Workspace
workspaceConcurrency: 4

# Many checkouts of the same repo
virtualStoreType: global

Quick Reference