Why Choose pnpm for Package Management

pnpm offers faster installs and better disk usage. Here's why you should consider switching.

Key Benefits#

# Install pnpm
npm install -g pnpm

# Or with corepack
corepack enable
corepack prepare pnpm@latest --activate

# Check version
pnpm --version

Content-Addressable Storage#

Traditional npm:
project-a/node_modules/lodash/
project-b/node_modules/lodash/
project-c/node_modules/lodash/
# 3 copies of lodash

pnpm:
~/.pnpm-store/
  lodash@4.17.21/  # Single copy
project-a/node_modules/.pnpm/lodash@4.17.21
project-b/node_modules/.pnpm/lodash@4.17.21
project-c/node_modules/.pnpm/lodash@4.17.21
# All symlinked to store

# View store stats
pnpm store status

# Prune unused packages
pnpm store prune

# Check disk usage
du -sh ~/.pnpm-store

Strict Node Modules#

// npm allows accessing undeclared dependencies (hoisting)
// This works with npm but shouldn't:
import something from 'transitive-dep'; // Not in package.json

// pnpm enforces strict mode
// You can only import declared dependencies
// This prevents phantom dependencies

# If you need hoisting (legacy compatibility)
# .npmrc
node-linker=hoisted
shamefully-hoist=true

Common Commands#

# Install all dependencies
pnpm install
pnpm i

# Add dependency
pnpm add lodash
pnpm add -D typescript      # Dev dependency
pnpm add -O webpack         # Optional dependency
pnpm add lodash@4.17.21     # Specific version

# Remove dependency
pnpm remove lodash
pnpm rm lodash

# Update dependencies
pnpm update
pnpm up lodash              # Update specific
pnpm up --latest           # Update to latest (ignoring semver)

# Run scripts
pnpm run build
pnpm build                  # Shorthand

# Execute package binary
pnpm exec tsc
pnpm dlx create-react-app   # Like npx

Lockfile#

# pnpm-lock.yaml (more readable than package-lock.json)
lockfileVersion: '9.0'

settings:
  autoInstallPeers: true

importers:
  .:
    dependencies:
      react:
        specifier: ^18.2.0
        version: 18.2.0

packages:
  react@18.2.0:
    resolution: {integrity: sha512-...}
    engines: {node: '>=0.10.0'}

Workspaces (Monorepo)#

# pnpm-workspace.yaml
packages:
  - 'packages/*'
  - 'apps/*'
  - '!**/test/**'

# Install all workspace dependencies
pnpm install

# Run command in specific package
pnpm --filter @myorg/web build
pnpm -F @myorg/web build

# Run command in all packages
pnpm -r build
pnpm --recursive build

# Run command in packages that changed
pnpm -F '...[origin/main]' build

# Add dependency to workspace package
pnpm add lodash --filter @myorg/utils

# Add workspace package as dependency
pnpm add @myorg/utils --filter @myorg/web --workspace

// packages/web/package.json
{
  "name": "@myorg/web",
  "dependencies": {
    "@myorg/utils": "workspace:*"
  }
}

Performance Comparison#

# Benchmark (typical results)
# Clean install:
npm install    # ~45 seconds
yarn install   # ~35 seconds
pnpm install   # ~15 seconds

# With cache:
npm install    # ~20 seconds
yarn install   # ~10 seconds
pnpm install   # ~5 seconds

# Disk usage (10 similar projects):
npm            # ~2.5 GB
yarn           # ~2.5 GB
pnpm           # ~500 MB (shared store)

Configuration#

# .npmrc
# Strict peer dependencies
auto-install-peers=true
strict-peer-dependencies=true

# Use specific store location
store-dir=~/.pnpm-store

# Prefer offline
prefer-offline=true

# Registry
registry=https://registry.npmjs.org/

# Workspace settings
link-workspace-packages=true
shared-workspace-lockfile=true

Scripts and Hooks#

// package.json
{
  "scripts": {
    "preinstall": "npx only-allow pnpm",
    "prepare": "husky install"
  },
  "packageManager": "pnpm@8.15.0"
}

# Run pre/post hooks
pnpm run prebuild  # Runs before build
pnpm run build
pnpm run postbuild # Runs after build

Overrides and Patches#

// package.json
{
  "pnpm": {
    "overrides": {
      "lodash": "4.17.21",
      "foo@^1.0.0>bar": "2.0.0"
    },
    "patchedDependencies": {
      "some-package@1.0.0": "patches/some-package.patch"
    }
  }
}

# Create patch
pnpm patch some-package@1.0.0
# Edit files in temporary directory
pnpm patch-commit <path>

CI/CD Setup#

# GitHub Actions
name: CI

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v3
        with:
          version: 8

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'

      - run: pnpm install --frozen-lockfile
      - run: pnpm build
      - run: pnpm test

# Dockerfile
FROM node:20-alpine

RUN corepack enable

WORKDIR /app

COPY pnpm-lock.yaml package.json ./
RUN pnpm install --frozen-lockfile --prod

COPY . .
RUN pnpm build

CMD ["node", "dist/index.js"]

Migration from npm/yarn#

# Import from package-lock.json
pnpm import

# Remove npm/yarn files
rm -rf node_modules package-lock.json yarn.lock

# Install with pnpm
pnpm install

# Verify
pnpm ls

Troubleshooting#

# Clear cache
pnpm store prune

# Rebuild node_modules
rm -rf node_modules
pnpm install

# Check for issues
pnpm why lodash        # Why is package installed
pnpm ls --depth 2      # List dependencies
pnpm outdated          # Check for updates

# Verify store integrity
pnpm store verify

Best Practices#

Project Setup:
✓ Add packageManager to package.json
✓ Use preinstall to enforce pnpm
✓ Commit pnpm-lock.yaml
✓ Configure .npmrc for team

Performance:
✓ Use --frozen-lockfile in CI
✓ Enable prefer-offline
✓ Prune store periodically
✓ Use workspace protocol

Monorepos:
✓ Define pnpm-workspace.yaml
✓ Use workspace: protocol
✓ Filter commands appropriately
✓ Share common configurations

pnpm provides faster installs, better disk usage, and stricter dependency management. Its content-addressable store eliminates duplication, while strict mode prevents phantom dependencies. For monorepos, workspace support makes it an excellent choice for managing multiple packages.