pnpm

pnpm is a fast, disk-efficient package manager for JavaScript that uses a content-addressable store and symlinked node_modules to eliminate duplicate dependencies across projects.

When to Use

• Fast, Disk-Efficient JavaScript Package Management: Saving gigabytes of disk space via a content-addressable hard-link store.
• Strict Dependency Resolution: Eliminating phantom dependencies (preventing access to unlisted transitive packages).
• Enterprise Monorepos: Scaling multi-package workspaces with pnpm-workspace.yaml and fast parallel execution.
• Continuous Integration Optimization: Slashing CI installation times by up to 2x-3x through global store caching.

Quick Start

# Enable via Corepack
corepack enable
corepack prepare pnpm@latest --activate

pnpm add next

Core Concepts

Configuring Monorepo Workspaces (pnpm-workspace.yaml)

Declaring workspace packages and root settings:

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

// packages/core-service/package.json
{
  "name": "@my-org/core-service",
  "version": "1.0.0",
  "dependencies": {
    "@my-org/shared-utils": "workspace:*" // Symlinks to local workspace package
  }
}

Workspace Commands & Parallel Script Execution

Running builds and tests across packages:

# Run tests in parallel across all workspace packages
pnpm --recursive run test

# Run build only for packages modified since main branch
pnpm --filter "...[origin/main]" run build

# Install a shared dependency to a specific package
pnpm --filter @my-org/web-app add lucide-react

Hard Links and Content-Addressable Store

Inspecting and pruning global package deduplication:

# Verify integrity of global content-addressable store
pnpm store status

# Clean up unreferenced packages to free disk space
pnpm store prune

Common Patterns

Monorepo Workspaces with Shared Internal Packages

Problem: Inefficient symlinking and phantom dependency hoisting in large JavaScript monorepos.

Solution: Define clean workspace structure in pnpm-workspace.yaml:

packages:
  - "apps/*"
  - "packages/*"

Consume internal package with workspace:* protocol:

{
  "dependencies": {
    "@myorg/ui": "workspace:*",
    "@myorg/utils": "workspace:*"
  }
}

Best Practices

Do:

• Use pnpm install --frozen-lockfile in CI/CD pipelines to guarantee reproducible installs.
• Use workspace:* protocols for internal dependencies to ensure local development links without publishing.
• Leverage --filter to run commands only on modified packages and their dependents.
• Manage pnpm versions via Corepack (corepack enable pnpm) to align team versions.

Don't:

• Access transitive packages not explicitly declared in package.json; pnpm's strict layout prevents this.
• Commit the global .pnpm-store to version control.
• Mix multiple package managers (npm, yarn) in the same project directory.

Troubleshooting

References

• pnpm Documentation