pnpm Workspaces: Monorepo Management Guide

pnpm's efficient storage model and workspace support make it ideal for monorepos.

Setup

# pnpm-workspace.yaml
packages:
  - 'packages/*'
  - 'apps/*'
  - '!**/test/**'

// package.json (root)
{
  "name": "my-monorepo",
  "private": true,
  "scripts": {
    "build": "pnpm -r build",
    "test": "pnpm -r test",
    "lint": "pnpm -r lint"
  },
  "devDependencies": {
    "typescript": "^5.0.0"
  }
}

Workspace Structure

monorepo/
├── pnpm-workspace.yaml
├── package.json
├── packages/
│   ├── ui/
│   │   ├── package.json
│   │   └── src/
│   └── utils/
│       ├── package.json
│       └── src/
└── apps/
    ├── web/
    │   └── package.json
    └── api/
        └── package.json

Cross-Package Dependencies

// apps/web/package.json
{
  "name": "@myrepo/web",
  "dependencies": {
    "@myrepo/ui": "workspace:*",
    "@myrepo/utils": "workspace:*"
  }
}

Filtering Commands

# Run in specific package
pnpm --filter @myrepo/web dev

# Run in all packages matching pattern
pnpm --filter "./packages/**" build

# Run with dependencies
pnpm --filter @myrepo/web... build

# Run in changed packages
pnpm --filter "[origin/main]" test

Shared Configs

// packages/tsconfig/base.json
{
  "compilerOptions": {
    "target": "ES2022",
    "strict": true,
    "moduleResolution": "bundler"
  }
}

// apps/web/tsconfig.json
{
  "extends": "@myrepo/tsconfig/base.json",
  "include": ["src"]
}

Catalogs (pnpm v9+)

# pnpm-workspace.yaml
catalog:
  react: ^18.2.0
  typescript: ^5.0.0

// packages/ui/package.json
{
  "dependencies": {
    "react": "catalog:"
  }
}

pnpm's content-addressable storage saves disk space by sharing package files across projects.