name: pnpm
description: Best practices for pnpm package manager, workspace management, and monorepo configuration

pnpm Development

You are an expert in pnpm, the fast, disk space efficient package manager for JavaScript and TypeScript projects.

Core Principles

• Always use pnpm (not npm or yarn) for package management
• Leverage pnpm's strict dependency resolution for better security
• Use the content-addressable store for disk space efficiency
• Maintain consistent lockfile (pnpm-lock.yaml)

Installation and Setup

• Install pnpm globally: npm install -g pnpm
• Or use corepack: corepack enable && corepack prepare pnpm@latest --activate
• Specify pnpm version in package.json:
  json { "packageManager": "[email protected]" }

Workspace Configuration

Create pnpm-workspace.yaml for monorepo setup:

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

• Use glob patterns to define workspace package locations
• All matched directories with package.json become workspace packages

Dependency Management

• Install dependencies: pnpm install
• Add dependencies to specific workspace:
  bash pnpm add lodash --filter @org/my-app pnpm add -D typescript --filter @org/my-lib
• Use workspace protocol for internal dependencies:
  json { "dependencies": { "@org/shared-utils": "workspace:*", "@org/ui": "workspace:^" } }
• Protocol options:
• workspace:* - Any version, replaced with actual version on publish
• workspace:^ - Compatible versions
• workspace:~ - Patch versions only

Filtering Commands

Run commands in specific packages:

pnpm --filter @org/my-app dev
pnpm --filter "./apps/*" build
pnpm --filter "...@org/my-lib" test  # Include dependents
pnpm --filter "@org/my-lib..." build  # Include dependencies

• Filter patterns:
• --filter <package-name> - Specific package
• --filter "./path/*" - By path
• --filter "...<pkg>" - Package and its dependents
• --filter "<pkg>..." - Package and its dependencies

Scripts and Task Running

• Run scripts across workspaces:
  bash pnpm -r run build # Run in all packages pnpm -r --parallel run dev # Run in parallel pnpm -r --stream run test # Stream output
• Define root-level scripts for common operations:
  json { "scripts": { "build": "pnpm -r run build", "dev": "pnpm --filter @org/web dev", "lint": "pnpm -r run lint", "test": "pnpm -r run test" } }

Dependency Hoisting

Configure hoisting in .npmrc:

# Strict mode - no hoisting
hoist=false

# Selective hoisting
public-hoist-pattern[]=*eslint*
public-hoist-pattern[]=*prettier*

# Shamefully hoist everything (not recommended)
shamefully-hoist=true

• Prefer strict mode for better dependency isolation
• Use public hoisting for tools that need flat node_modules

Peer Dependencies

Configure peer dependency handling in .npmrc:

auto-install-peers=true
strict-peer-dependencies=false

• Resolve peer dependency warnings appropriately
• Document required peer dependencies clearly

Overrides and Resolutions

Override dependencies in root package.json:

{
  "pnpm": {
    "overrides": {
      "lodash": "^4.17.21",
      "[email protected]": "npm:bar@^2.0.0"
    }
  }
}

• Use overrides to fix security vulnerabilities
• Pin problematic transitive dependencies

Publishing Workspaces

• Configure publishable packages with proper fields
• Publish with pnpm publish
• Workspace protocol references are replaced with actual versions

Performance Optimization

• Use pnpm fetch in Docker for better caching:
  dockerfile COPY pnpm-lock.yaml ./ RUN pnpm fetch COPY . ./ RUN pnpm install --offline
• Configure store location for CI caching
• Use --frozen-lockfile in CI environments

Best Practices

• Always commit pnpm-lock.yaml
• Use .npmrc for consistent team configuration
• Prefer workspace:* for internal dependencies
• Keep root package.json minimal
• Use pnpm dedupe to optimize lockfile
• Audit regularly with pnpm audit
• Use pnpm why <package> to debug dependency issues
• Integrate with Turborepo or Nx for advanced task running
• Set engine-strict=true to enforce Node.js version requirements