/shared-monorepo-pnpm-workspaces

name: shared-monorepo-pnpm-workspaces
description: pnpm workspace protocol, filtering, catalogs, shared dependencies, publishing, and CI/CD for monorepo management

pnpm Workspaces for Monorepo Management

> **Quick Guide:** pnpm 10.x workspaces for monorepo management. `pnpm-workspace.yaml` defines workspace packages. `workspace:*` protocol for internal linking. `catalog:` protocol for dependency version synchronization. `--filter` for targeted commands. Shared `tsconfig` and tooling config across packages. Changesets for versioning and publishing. Strict dependency isolation by default.

---

<critical_requirements>

CRITICAL: Before Using This Skill

**(You MUST use `workspace:*` protocol for ALL internal package dependencies -- never hardcode versions)**

**(You MUST use `--frozen-lockfile` in CI -- pnpm enables this by default in CI environments)**

**(You MUST define workspace packages in `pnpm-workspace.yaml` at the repository root)**

**(You MUST put pnpm-specific settings in `pnpm-workspace.yaml` -- NOT `.npmrc` (pnpm v10 change))**

**(You MUST use `catalog:` protocol when sharing dependency versions across 3+ packages)**

**(You MUST use `--filter` for targeted commands instead of `pnpm -r` when only specific packages changed)**

</critical_requirements>

---

**Auto-detection:** pnpm-workspace.yaml, pnpm workspaces, workspace protocol, workspace:\*, catalog:, pnpm filter, pnpm recursive, pnpm monorepo, pnpm-lock.yaml, .npmrc pnpm, pnpm catalogs, pnpm publish

**When to use:**

• Setting up a monorepo with pnpm workspaces
• Configuring `pnpm-workspace.yaml` for workspace package discovery
• Linking internal packages with `workspace:*` protocol
• Synchronizing dependency versions with `catalog:` protocol
• Running scripts across workspaces with `--filter` or `-r`
• Publishing packages from a pnpm workspace
• Setting up CI/CD pipelines with pnpm caching
• Sharing TypeScript, ESLint, or Prettier config across workspace packages
• Migrating from npm/yarn workspaces to pnpm

**When NOT to use:**

• Single-package projects with no shared code
• Projects using Bun or Yarn as their package manager
• Projects that need npm compatibility exclusively (e.g., npm workspaces)
• Task orchestration logic (use a dedicated task runner on top of pnpm)

**Key patterns covered:**

• `pnpm-workspace.yaml` setup and workspace package discovery
• Workspace protocol (`workspace:*`, `workspace:^`, `workspace:~`)
• Catalogs for dependency version synchronization
• Filtering commands (`--filter`, `-F`, glob patterns, dependency selectors)
• Running scripts across workspaces (`-r`, `--parallel`, `--workspace-concurrency`)
• Settings in `pnpm-workspace.yaml` (v10: settings moved from `.npmrc`)
• Publishing with `publishConfig` and changesets
• CI/CD with GitHub Actions, caching, and `--frozen-lockfile`
• Shared TypeScript configuration patterns
• Monorepo directory structure conventions

**Detailed resources:**

• [Core Setup](examples/core.md) -- pnpm-workspace.yaml, .npmrc, directory structure, settings
• [Shared Packages](examples/packages.md) -- workspace protocol, catalogs, TypeScript/ESLint config
• [Scripts & Filtering](examples/scripts.md) -- --filter, recursive execution, dependency management
• [Publishing & Versioning](examples/publishing.md) -- changesets, publishConfig, Docker
• [CI/CD Pipelines](examples/ci.md) -- GitHub Actions, automated release
• [Quick Command Reference](reference.md) -- condensed lookup table

---

<philosophy>

Philosophy

pnpm workspaces provide strict, efficient monorepo management with content-addressable storage. Unlike npm/yarn, pnpm creates a non-flat `node_modules` where packages can only access their declared dependencies -- this strictness catches missing dependency declarations early. The workspace protocol (`workspace:*`) ensures internal packages always link locally, while catalogs (`catalog:`) centralize version management to eliminate version drift.

**Core principles:**

• **Strict by default** -- packages cannot access undeclared dependencies
• **Disk efficient** -- content-addressable store shares identical files across projects
• **Security first** -- v10 blocks lifecycle scripts by default to prevent supply chain attacks
• **Single lockfile** -- one `pnpm-lock.yaml` at the workspace root for all packages

**When to use pnpm workspaces:**

• Monorepos with multiple apps and shared packages
• Projects that need strict dependency isolation
• Teams that want disk-efficient dependency storage
• Publishing multiple related npm packages from one repo

**When NOT to use:**

• Single-package projects (no workspace benefits)
• Projects deeply invested in Yarn PnP or Berry features
• Environments where only npm is available (some CI/CD, restricted corporate setups)

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Workspace Configuration (`pnpm-workspace.yaml`)

The `pnpm-workspace.yaml` file at the repository root defines which directories contain workspace packages. Every pnpm workspace MUST have this file.

# pnpm-workspace.yaml
packages:
  - "apps/*"
  - "packages/*"

In pnpm v10, settings moved from `.npmrc` to this file:

# pnpm-workspace.yaml (v10+)
packages:
  - "apps/*"
  - "packages/*"

linkWorkspacePackages: true
saveWorkspaceProtocol: rolling
disallowWorkspaceCycles: true

**Why good:** Single source of truth for workspace definition and settings

See [examples/core.md](examples/core.md) for full workspace setup, directory structure, and all settings.

---

Pattern 2: Workspace Protocol (`workspace:*`)

The workspace protocol ensures internal packages always resolve to the local workspace version, never from the registry.

| Protocol | During Development | After `pnpm publish` | | ------------- | ---------------------- | ------------------------------------------- | | `workspace:*` | Links to local package | Replaced with exact version (e.g., `1.5.0`) | | `wor