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:
  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-apppnpm 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 devpnpm --filter "./apps/*" buildpnpm --filter "...@org/my-lib" test  # Include dependentspnpm --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 packagespnpm -r --parallel run dev  # Run in parallelpnpm -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 hoistinghoist=false
# Selective hoistingpublic-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=truestrict-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 fetchCOPY . ./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