PNPM Package Manager Guide

Overview

PNPM (Performant NPM) is a fast, disk space-efficient package manager that uses hard links and symlinks to save disk space and boost installation speed.

Why We Chose PNPM

1. Native Module Compatibility

PNPM handles native modules better than NPM, resolving issues with packages like:

lightningcss - CSS processing
@napi-rs/simple-git - Git operations
@prisma/client - Database ORM

2. Disk Space Efficiency

Uses a single content-addressable storage for all packages
Creates hard links instead of copying files
Saves ~30% disk space compared to NPM

3. Faster Installations

Parallel package resolution and fetching
Efficient caching mechanism
~40% faster than NPM for clean installs

4. Strict Dependency Resolution

Prevents phantom dependencies
Ensures reproducible builds
Better security through isolated dependencies

Installation

Global Installation


# Using npm
npm install -g pnpm@9.14.4
 
# Using homebrew (macOS)
brew install pnpm
 
# Using curl
curl -fsSL https://get.pnpm.io/install.sh | sh -

Version Management


# Check version
pnpm --version
 
# Update to latest
pnpm add -g pnpm

Configuration

`.npmrc` Configuration


# Enable hoisted node_modules for compatibility
node-linker=hoisted
 
# Strict peer dependencies
strict-peer-dependencies=false
 
# Auto install peers
auto-install-peers=true

Workspace Configuration


# pnpm-workspace.yaml
packages:
  - 'apps'
  - 'console'
  - 'docs-nextra'
  - 'credit-engine'

Common Commands

Basic Commands


# Install all dependencies
pnpm install
 
# Add a dependency
pnpm add package-name
 
# Add dev dependency
pnpm add -D package-name
 
# Remove dependency
pnpm remove package-name
 
# Update dependencies
pnpm update

Workspace Commands


# Run command in specific workspace
pnpm --filter console add package-name
pnpm --filter apps dev
 
# Run command in all workspaces
pnpm -r update
 
# Install dependencies for all workspaces
pnpm install --recursive

Turborepo Integration


# Build with Turborepo
pnpm turbo build
 
# Build specific project
pnpm turbo build --filter=console
 
# Run development servers
pnpm turbo dev
 
# Run with cache disabled
pnpm turbo build --force

Migration from NPM

Step 1: Clean Existing Installation


# Remove NPM artifacts
rm -rf node_modules
rm package-lock.json
find . -name "node_modules" -type d -prune -exec rm -rf {} +
find . -name "package-lock.json" -type f -delete

Step 2: Install with PNPM


# Install dependencies
pnpm install
 
# Verify installation
pnpm list

Step 3: Update Scripts


{
  "scripts": {
    "dev": "pnpm turbo dev",
    "build": "pnpm turbo build",
    "lint": "pnpm turbo lint"
  }
}

Best Practices

1. Lock File Management

Always commit pnpm-lock.yaml
Use pnpm install --frozen-lockfile in CI
Never manually edit the lock file

2. Workspace Dependencies


# Add shared dependency to root
pnpm add -w -D typescript
 
# Add dependency to specific workspace
pnpm --filter console add react
 
# Use workspace protocol for internal deps
pnpm --filter console add @earna/shared@workspace:*

3. Performance Optimization


# Prune store to free space
pnpm store prune
 
# Check store status
pnpm store status
 
# Verify integrity
pnpm install --verify-store-integrity

Troubleshooting

Issue: ELIFECYCLE Error


# Clear cache and reinstall
pnpm store prune
rm -rf node_modules pnpm-lock.yaml
pnpm install

Issue: Permission Errors


# Fix permissions (macOS/Linux)
sudo chown -R $(whoami) ~/.pnpm-store
sudo chown -R $(whoami) node_modules

Issue: Native Module Compilation


# Rebuild native modules
pnpm rebuild
 
# Rebuild specific package
pnpm rebuild sharp

Issue: Phantom Dependencies


# Check for phantom deps
pnpm why package-name
 
# List all dependencies
pnpm list --depth=0

Environment Variables

PNPM-Specific Variables


# Set store directory
PNPM_HOME=~/.pnpm
 
# Set cache directory
XDG_CACHE_HOME=~/.cache
 
# Concurrent network requests
PNPM_NETWORK_CONCURRENCY=16

Vercel Deployment


# In vercel.json or dashboard
PNPM_VERSION=9.14.4
VERCEL_DEEP_CLONE=true

Comparison with NPM

Feature	PNPM	NPM
Disk Usage	~30% less	Baseline
Install Speed	~40% faster	Baseline
Phantom Dependencies	Prevented	Allowed
Native Modules	Better support	Issues with some
Monorepo Support	Excellent	Good
Lock File	pnpm-lock.yaml	package-lock.json

Advanced Features

1. Patches


# Create a patch for a package
pnpm patch package-name
 
# Apply patches automatically
pnpm install

2. Overrides


{
  "pnpm": {
    "overrides": {
      "lodash": "^4.17.21",
      "react": "$react"
    }
  }
}

3. Hooks


{
  "pnpm": {
    "peerDependencyRules": {
      "ignoreMissing": ["@types/*"]
    }
  }
}

CI/CD Configuration

GitHub Actions


- name: Setup PNPM
  uses: pnpm/action-setup@v2
  with:
    version: 9.14.4
 
- name: Install dependencies
  run: pnpm install --frozen-lockfile

Vercel


{
  "installCommand": "pnpm install",
  "buildCommand": "pnpm turbo build --filter=app-name"
}