pnpm - Quick Reference

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: pnpm for comprehensive documentation.

When NOT to Use This Skill

• npm projects - Stick with npm unless migrating
• Yarn projects - Yarn 3+ has similar features
• Bun projects - Bun has its own package manager
• Legacy tooling - Some tools don't support pnpm

When to Use This Skill

• Efficient dependency management
• Monorepo setup and management
• Migration from npm/yarn
• CI/CD optimization

Setup

# Install pnpm
npm install -g pnpm

# Or via corepack (recommended)
corepack enable
corepack prepare pnpm@latest --activate

# Initialize project
pnpm init

Basic Commands

# Install all dependencies
pnpm install
pnpm i

# Add dependency
pnpm add express
pnpm add -D typescript @types/node   # devDependency
pnpm add -O lodash                   # optionalDependency
pnpm add -g serve                    # global

# Remove
pnpm remove express
pnpm rm express

# Update
pnpm update              # Update all
pnpm update express      # Update specific
pnpm update --latest     # Update to latest (ignore semver)

# Run scripts
pnpm run build
pnpm build              # Shorthand
pnpm dev
pnpm test

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

Lockfile & Reproducibility

# Frozen install (CI)
pnpm install --frozen-lockfile

# Prefer offline
pnpm install --prefer-offline

# Update lockfile only
pnpm install --lockfile-only

# Import from npm/yarn
pnpm import

Workspaces (Monorepo)

Setup

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

my-monorepo/
├── pnpm-workspace.yaml
├── package.json
├── apps/
│   ├── web/
│   │   └── package.json
│   └── api/
│       └── package.json
└── packages/
    ├── ui/
    │   └── package.json
    └── utils/
        └── package.json

Workspace Commands

# Install all workspaces
pnpm install

# Run in specific workspace
pnpm --filter @myorg/web dev
pnpm -F @myorg/web dev          # Shorthand

# Run in all workspaces
pnpm -r build
pnpm --recursive build

# Run in workspaces matching pattern
pnpm --filter "./apps/*" build
pnpm --filter "...@myorg/ui" build   # ui and dependents

# Add dependency to workspace
pnpm --filter @myorg/web add react

# Add workspace dependency
pnpm --filter @myorg/web add @myorg/ui --workspace

Workspace Protocol

// apps/web/package.json
{
  "name": "@myorg/web",
  "dependencies": {
    "@myorg/ui": "workspace:*",     // Any version
    "@myorg/utils": "workspace:^",  // Compatible
    "@myorg/config": "workspace:~"  // Patch updates
  }
}

Filtering

# By name
pnpm --filter @myorg/web build

# By directory
pnpm --filter ./apps/web build

# By pattern
pnpm --filter "@myorg/*" build
pnpm --filter "!@myorg/deprecated" build

# Dependencies
pnpm --filter @myorg/web... build     # web + dependencies
pnpm --filter ...@myorg/ui build      # ui + dependents
pnpm --filter @myorg/web^... build    # only dependencies (not web)

# Since git ref
pnpm --filter "...[origin/main]" build  # Changed since main

Configuration

.npmrc

# .npmrc
# Hoist patterns
public-hoist-pattern[]=*types*
public-hoist-pattern[]=*eslint*

# Strict peer deps
strict-peer-dependencies=true

# Auto-install peers
auto-install-peers=true

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

# Scoped registry
@myorg:registry=https://npm.pkg.github.com

# Authentication
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

# Store location
store-dir=~/.pnpm-store

# Symlinks
node-linker=hoisted  # For compatibility

package.json

{
  "name": "my-monorepo",
  "private": true,
  "packageManager": "pnpm@9.0.0",
  "engines": {
    "node": ">=20",
    "pnpm": ">=9"
  },
  "scripts": {
    "build": "pnpm -r build",
    "dev": "pnpm --parallel -r dev",
    "lint": "pnpm -r lint",
    "test": "pnpm -r test",
    "clean": "pnpm -r exec rm -rf dist node_modules"
  }
}

Shared Dependencies

Catalog (pnpm 9+)

# pnpm-workspace.yaml
packages:
  - 'packages/*'

catalog:
  react: ^18.2.0
  react-dom: ^18.2.0
  typescript: ^5.4.0
  vitest: ^1.6.0

// packages/web/package.json
{
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:"
  }
}

Shared Config

// package.json (root)
{
  "devDependencies": {
    "typescript": "^5.4.0",
    "eslint": "^9.0.0"
  }
}

// packages/web/package.json
{
  "devDependencies": {
    "typescript": "workspace:*"  // Inherit from root
  }
}

CI/CD

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: 9

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

      - name: Install
        run: pnpm install --frozen-lockfile

      - name: Build
        run: pnpm -r build

      - name: Test
        run: pnpm -r test

Caching

# Cache pnpm store
- uses: actions/cache@v4
  with:
    path: ~/.pnpm-store
    key: pnpm-${{ runner.os }}-${{ hashFiles('**/pnpm-lock.yaml') }}
    restore-keys: |
      pnpm-${{ runner.os }}-

Patching

# Create patch
pnpm patch express@4.18.2

# Edit in temp directory, then
pnpm patch-commit <path-to-temp>

// package.json
{
  "pnpm": {
    "patchedDependencies": {
      "express@4.18.2": "patches/express@4.18.2.patch"
    }
  }
}

Overrides

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

Migration from npm/yarn

# Remove old lock files
rm package-lock.json yarn.lock

# Import existing lockfile
pnpm import

# Install
pnpm install

# Verify
pnpm ls

Common Issues

# Peer dependency issues
pnpm install --strict-peer-dependencies=false

# Hoist issues (certain packages need hoisting)
# Add to .npmrc:
public-hoist-pattern[]=*prisma*
shamefully-hoist=true  # Last resort!

# Symlink issues (Windows/Docker)
# Add to .npmrc:
node-linker=hoisted

Performance Tips

# Parallel execution
pnpm --parallel -r dev

# Limit concurrency
pnpm -r --workspace-concurrency=4 build

# Skip already built
pnpm -r build --filter "...[origin/main]"

# Prune store
pnpm store prune

# Store status
pnpm store status

Comparison

Feature	npm	yarn	pnpm
Disk usage	High	High	Low (content-addressable)
Install speed	Medium	Fast	Fastest
Monorepo	Workspaces	Workspaces	Best
Strictness	Low	Low	High
Plug'n'Play	No	Yes	No

Anti-Patterns to Avoid

• Do not use shamefully-hoist without reason
• Do not forget --frozen-lockfile in CI
• Do not ignore peer dependency warnings
• Do not mix package managers in the same repo

Anti-Patterns

Anti-Pattern	Why It's Bad	Correct Approach
Using shamefully-hoist	Breaks dependency isolation	Use public-hoist-pattern selectively
Missing --frozen-lockfile in CI	Non-reproducible builds	Always use in CI/CD
Ignoring peer dependency warnings	Runtime errors	Resolve peer deps or use auto-install-peers
Mixing package managers	Lock file conflicts	Commit only one lock file type
Not using workspace protocol	Version conflicts	Use workspace:* for internal deps
Missing packageManager field	Wrong pnpm version	Add to package.json

Quick Troubleshooting

Issue	Cause	Solution
Module not found	Strict isolation	Add to public-hoist-pattern or fix imports
Peer dependency errors	Unresolved peers	Set auto-install-peers: true or install manually
Wrong pnpm version	No packageManager field	Add "packageManager": "pnpm@9.0.0"
Symlink issues (Windows)	File system permissions	Run as admin or use node-linker: hoisted
Slow installs	No offline mode	Use --prefer-offline
Workspace not found	Wrong pnpm-workspace.yaml	Check packages patterns

Checklist

• pnpm-workspace.yaml configured
• .npmrc with appropriate configurations
• packageManager in package.json
• CI with --frozen-lockfile
• Cache configured in CI
• Catalogs for shared versions (pnpm 9+)

Further Reading

For advanced configurations: mcp__documentation__fetch_docs

• Technology: pnpm
• pnpm Docs