# Pnpm Workspaces

> Use to plan a pnpm-workspaces monorepo — workspace layout, internal package linking (workspace protocol), dependency hoisting/isolation policy, versioning of shared packages, and lockfile/CI discipline. Configuration planning; does not scaffold apps.

- Skill: `ahtishamshahzad/pnpm-workspaces` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ahtishamshahzad/pnpm-workspaces`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ahtishamshahzad/pnpm-workspaces/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ahtishamshahzad (https://skillmd.com/u/ahtishamshahzad)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ahtishamshahzad/pnpm-workspaces

---


# pnpm Workspaces

## Purpose

Set up a pnpm-based monorepo so internal packages link cleanly, dependencies stay isolated, and installs are fast and reproducible — the workspace foundation chosen by `monorepo-selection`, with or without Turborepo on top.

## When to Use

- After `monorepo-selection` chose pnpm workspaces.
- **Not** for npm-workspace repos (`npm-workspaces`) or single repos.

## Inputs

- The package/app inventory and which packages are shared (contracts, types, utils).
- Node/pnpm version policy; whether Turborepo orchestrates (`turborepo-foundation`).

## Discovery Questions

- What is the workspace layout (`apps/*`, `packages/*`) and which packages are internal-shared?
- Which internal packages depend on which (via the workspace protocol)?
- What Node/pnpm versions are pinned, and how is the lockfile enforced in CI?

## Responsibilities

- Define `pnpm-workspace.yaml` **package globs** and a clear `apps/` vs `packages/` layout.
- Link internal packages with the **`workspace:` protocol** so cross-package deps resolve to local source, not the registry.
- Set the **dependency policy**: pnpm's strict isolation (no phantom deps) is a feature — each package declares what it imports; avoid loosening hoisting unless a tool genuinely needs it (record why).
- Handle **shared-package versioning**: internal packages either move in lockstep (unversioned/`workspace:*`) or are independently versioned/published — decide and record.
- Enforce **reproducibility**: committed `pnpm-lock.yaml`, `--frozen-lockfile` in CI, pinned pnpm version (via `packageManager` field / corepack).
- Coordinate with `docker-foundation` (workspace-aware, cached installs in images) and `ci-cd` (frozen installs, affected-only with Turborepo).

## Required Workflow

1. Define workspace globs + layout.
2. Wire internal deps via `workspace:` protocol.
3. Set the isolation/hoisting policy (keep strict by default).
4. Decide shared-package versioning.
5. Enforce lockfile + pinned-version discipline in CI.

## Decision Rules

- Keep pnpm's strict isolation — phantom-dependency bugs it prevents are real; loosen only with a recorded reason.
- `workspace:` protocol for all internal deps — never registry versions for local packages.
- `--frozen-lockfile` in CI; a drifting lockfile is a reproducibility bug.
- Pin the package manager version so every environment installs identically.

## Rules

- Lockfile committed and frozen in CI.
- Each package declares its own dependencies (no relying on hoisted phantoms).
- Node/pnpm versions pinned across environments.

## Anti-Patterns

- Registry versions for internal packages instead of `workspace:`.
- Loosening hoisting globally to "fix" a missing declared dependency.
- Uncommitted or unfrozen lockfile → non-reproducible installs.
- Unpinned pnpm version drifting between local and CI.
- Flat, unstructured package layout.

## Validation Checklist

- [ ] Workspace globs + apps/packages layout defined.
- [ ] Internal deps via `workspace:` protocol.
- [ ] Isolation policy set (strict by default; exceptions recorded).
- [ ] Shared-package versioning decided.
- [ ] Frozen lockfile + pinned pnpm in CI.

## Definition of Done

A pnpm-workspace setup with a clear layout, `workspace:`-linked internal packages, strict dependency isolation, a recorded versioning policy, and frozen, pinned, reproducible installs across environments.

## Related Skills

`monorepo-selection`, `turborepo-foundation`, `npm-workspaces`, `docker-foundation`, `ci-cd`, `../../security/dependency-security`.

## Related Knowledge

`../../../knowledge/` (package graph, version policy).

## Related References

`../../../references/devops/` (workspace patterns, when populated).

## Context Loading Guidance

- **Requires:** package inventory, internal dep graph, version policy.
- **Does not require:** app feature code, unrelated infra.
- **May load:** `turborepo-foundation`, `ci-cd`.
- **Stop when:** layout, linking, isolation, versioning, and lockfile discipline are set.

## Token Efficiency Guidance

The layout + internal-dep list is the artifact; keep policy to the isolation and versioning decisions.