Setting the file. One moment.
Subchapter 6.3
references/best-practices-performance.mdMarkdown5 KBView on GitHub
pnpm is fast by default, but these optimizations can make it even faster.
Skip resolution when lockfile exists:
pnpm install --frozen-lockfileThis is faster because pnpm skips the resolution phase entirely.
Use cached packages when available:
pnpm install --prefer-offlineIf you don’t need optional deps:
pnpm install --no-optionalFor CI or when scripts aren’t needed:
pnpm install --ignore-scriptsCaution: Some packages require postinstall scripts to work correctly.
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 skipPackages not listed are treated as unreviewed (blocked by default). See features-supply-chain-security for the full build-approval workflow.
Cache native module build results (enabled by default):
sideEffectsCache: trueThis caches the results of postinstall scripts, speeding up subsequent installs.
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.
enableGlobalVirtualStore: trueA single content-addressable store is used for all projects by default:
storeDir: ~/.local/share/pnpm/storeBenefits: packages downloaded once, hard links save disk space, faster cached installs.
Periodically clean unused packages:
# Remove unreferenced packages
pnpm store prune
# Check store integrity
pnpm store statusRun workspace scripts in parallel:
pnpm -r --parallel run buildControl concurrency:
workspaceConcurrency: 8See output in real-time:
pnpm -r --stream run buildOnly build what changed:
# Build packages changed since main branch
pnpm --filter "...[origin/main]" run buildBuild dependencies before dependents:
pnpm -r run build
# Automatically runs in topological orderFor explicit sequential builds:
pnpm -r --workspace-concurrency=1 run buildNetwork/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:8080Use shared lockfile for all packages (default):
sharedWorkspaceLockfile: trueBenefits:
Only update lockfile without installing:
pnpm install --lockfile-only# 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-offlineDebug slow installs:
# Verbose logging
pnpm install --reporter=append-only
# Debug mode
DEBUG=pnpm:* pnpm installOptimized 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
enableGlobalVirtualStore: true| Scenario | Command/Setting |
|---|---|
| CI installs | pnpm ci / pnpm install --frozen-lockfile |
| Offline development | --prefer-offline |
| Control native builds | allowBuilds map |
| Parallel workspace | pnpm -r --parallel run build |
| Build changed only | pnpm --filter "...[origin/main]" build |
| Clean store | pnpm store prune |
| Many worktrees/agents | enableGlobalVirtualStore: true |