/pnpm

Workspaces & Configuration

pnpm-workspace.yaml

packages:
  - 'packages/*'
  - 'apps/*'
  - 'tools/*/packages/*'
  - '!**/test/**'  # Exclude

# Catalogs for shared versions
catalog:
  react: ^18.2.0
  typescript: ~5.3.0
  vite: ^5.0.0

catalogs:
  react17:
    react: ^17.0.2
    react-dom: ^17.0.2
  react18:
    react: ^18.2.0
    react-dom: ^18.2.0

# Overrides
overrides:
  lodash: ^4.17.21
  'foo@^1.0.0>bar': ^2.0.0

# Settings (alternative to .npmrc)
settings:
  auto-install-peers: true
  strict-peer-dependencies: false
  link-workspace-packages: true

Workspace Protocol

Reference local packages:

{
  "dependencies": {
    "@myorg/utils": "workspace:*",
    "@myorg/core": "workspace:^",
    "@myorg/types": "workspace:~"
  }
}

Catalogs

Centralized version management:

# pnpm-workspace.yaml
catalog:
  lodash: ^4.17.21
  zod: ^3.22.0

// package.json
{
  "dependencies": {
    "lodash": "catalog:",
    "zod": "catalog:"
  }
}

Named catalogs:

{
  "dependencies": {
    "react": "catalog:react18"
  }
}

On publish, catalog: becomes actual version.

.npmrc Settings

# Peer deps
auto-install-peers=true
strict-peer-dependencies=false

# Hoisting
public-hoist-pattern[]=*types*
public-hoist-pattern[]=*eslint*
shamefully-hoist=false

# Store
store-dir=~/.pnpm-store
virtual-store-dir=node_modules/.pnpm

# Lockfile
lockfile=true
prefer-frozen-lockfile=true

# Performance
side-effects-cache=true

# Registry
registry=https://registry.npmjs.org/
@myorg:registry=https://npm.myorg.com/

# Workspace
link-workspace-packages=true
prefer-workspace-packages=true
shared-workspace-lockfile=true
save-workspace-protocol=rolling

# Node.js
use-node-version=20.10.0
node-version-file=.nvmrc

package.json pnpm Field

{
  "pnpm": {
    "overrides": {
      "lodash": "^4.17.21"
    },
    "peerDependencyRules": {
      "ignoreMissing": ["@babel/*"],
      "allowedVersions": { "react": "17 || 18" },
      "allowAny": ["@types/*"]
    },
    "neverBuiltDependencies": ["fsevents"],
    "onlyBuiltDependencies": ["esbuild"],
    "patchedDependencies": {
      "express@4.18.2": "patches/express@4.18.2.patch"
    }
  }
}

Configuration Hierarchy

1. /etc/npmrc - Global
2. ~/.npmrc - User
3. <project>/.npmrc - Project
4. npm_config_<key>=<value> - Environment
5. pnpm-workspace.yaml settings

Project Structure

my-monorepo/
├── pnpm-workspace.yaml
├── package.json
├── pnpm-lock.yaml
├── .npmrc
├── packages/
│   ├── core/
│   │   └── package.json
│   ├── utils/
│   │   └── package.json
│   └── types/
│       └── package.json
└── apps/
    ├── web/
    │   └── package.json
    └── api/
        └── package.json

Workspace Scripts

# Install specific package dep
pnpm --filter @myorg/app add lodash

# Add workspace dep
pnpm --filter @myorg/app add @myorg/utils

# Run in topological order
pnpm -r run build

# Run in parallel
pnpm -r --parallel run test

# Execute in all packages
pnpm -r exec rm -rf dist

Publishing

pnpm publish -r                    # Publish all changed
pnpm publish -r --no-git-checks    # CI mode

workspace:* → actual version on publish.