pnpm Development

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": "pnpm@9.0.0"
  }

Workspace Configuration

pnpm-workspace.yaml

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

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

.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

.npmrc

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

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

Overrides and Resolutions

package.json

{
  "pnpm": {
    "overrides": {
      "lodash": "^4.17.21",
      "foo@1.x": "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