An Introduction to pnpm: A Faster Alternative to npm and Yarn

If you’ve ever watched your CI/CD pipeline spend minutes installing dependencies or struggled with disk space on development machines due to duplicate packages across projects, you’re experiencing the exact problems pnpm was designed to solve. This performant package manager offers a fundamentally different approach to dependency management that can cut installation times by 2-3× and reduce disk usage by approximately 50%.

What Makes pnpm Different

Unlike npm and Yarn, which duplicate packages across projects, pnpm uses a content-addressable store with hard links to share dependencies globally. When you install Express in multiple projects, npm creates separate copies in each node_modules folder. pnpm stores it once in ~/.pnpm-store and creates hard links to that single copy, dramatically reducing disk usage while maintaining complete isolation between projects.

This architecture also prevents “phantom dependencies”—a common issue where code can accidentally import packages not listed in package.json. With pnpm’s strict Node.js module resolution, if a dependency isn’t explicitly declared, your code can’t access it, catching errors before they reach production.

Installation and Setup

For Node.js 16.13 or later, the recommended installation method uses Corepack:

corepack enable
corepack prepare pnpm@latest --activate

Alternatively, install via npm:

npm install -g pnpm

Essential Commands for Daily Development

The core pnpm commands mirror npm’s familiar syntax while adding performance optimizations:

pnpm add express          # Add production dependency
pnpm add -D typescript    # Add dev dependency
pnpm remove lodash       # Remove package
pnpm update             # Update all dependencies
pnpm run build         # Execute script from package.json

The pnpm store command provides unique functionality for managing the global package cache:

pnpm store status      # Check store health
pnpm store prune      # Remove unreferenced packages

Configuration for Modern Projects

Create a .npmrc file to configure pnpm behavior for your team:

strict-peer-dependencies=true
auto-install-peers=true
prefer-offline=true

These settings enforce peer dependency requirements, automatically install peer dependencies (Node.js 16+), and prioritize cached packages to speed up installations.

Workspace Setup for Monorepos

For monorepo projects, pnpm’s workspace support excels at managing multiple packages. Create a pnpm-workspace.yaml file:

packages:
  - 'packages/*'
  - 'apps/*'

Link workspace packages using the workspace: protocol in package.json:

{
  "dependencies": {
    "@myapp/shared": "workspace:*",
    "@myapp/ui": "workspace:^1.0.0"
  }
}

Run commands across all workspace packages:

pnpm -r build                  # Build all packages
pnpm --filter @myapp/api dev   # Run dev script in specific package

CI/CD Optimization

For GitHub Actions, use the official pnpm action with Node.js 22 LTS:

- uses: pnpm/action-setup@v4
  with:
    version: 9
- uses: actions/setup-node@v4
  with:
    node-version: 22
    cache: 'pnpm'
- run: pnpm install --frozen-lockfile
- run: pnpm test

For GitLab CI, configure caching to maximize CI/CD optimization:

image: node:22

before_script:
  - corepack enable
  - corepack prepare pnpm@latest --activate

cache:
  key: pnpm-store-$CI_COMMIT_REF_SLUG
  paths:
    - .pnpm-store

install:
  script:
    - pnpm config set store-dir .pnpm-store
    - pnpm install --frozen-lockfile

The --frozen-lockfile flag ensures reproducible builds by failing if pnpm-lock.yaml doesn’t match package.json, preventing drift between development and production environments.

Performance in Practice

Teams migrating from npm typically see installation speeds improve by 2-3× due to pnpm’s efficient linking strategy. A medium-sized project with 500 dependencies might take 60 seconds with npm but only 20-25 seconds with pnpm. Disk savings are even more dramatic—developers working on multiple projects often reclaim 5-10GB of space as duplicate packages are eliminated.

Conclusion

pnpm delivers on its promise of faster, more efficient dependency management through innovative architecture rather than incremental improvements. Its strict dependency resolution catches errors early, while workspace setup capabilities make it ideal for modern monorepo architectures. Whether you’re optimizing CI/CD pipelines or managing complex full-stack applications, pnpm provides the performance and reliability that development teams need without sacrificing compatibility with the existing npm ecosystem.

FAQs

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.