pnpm

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:

  {
    "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:

  pnpm add lodash --filter @org/my-app
  pnpm add -D typescript --filter @org/my-lib
  

• Use workspace protocol for internal dependencies:

  {
    "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:

  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:

  {
    "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:

  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