Adopting pnpm Workspaces with a Single Lockfile and Filtered CI Builds

Problem & Takeaway

In a JavaScript/TypeScript monorepo you often have dozens of packages that ship independently but share common utilities. Reproducible installs, fast CI, and clear dependency boundaries are hard to maintain with npm or yarn when you want to avoid unnecessary rebuilds. pnpm’s isolated node_modules layout, a single root lockfile, and its powerful --filter syntax provide a clean architecture that satisfies these needs.

Key takeaway: Keep one pnpm-lock.yaml at the repo root, enable workspaces=true, and use pnpm --filter in CI to rebuild only affected packages and their dependents. This gives deterministic installs, prevents phantom dependencies, and keeps CI fast.

Requirements

• Multiple deployable packages that share internal libraries.
• Reproducible installs across local and CI environments.
• CI should skip unchanged packages to reduce build time.
• No accidental reliance on hoisted transitive dependencies.

Minimal Design

The smallest viable repository layout is:

repo-root/
├─ pnpm-workspace.yaml
├─ pnpm-lock.yaml
├─ .npmrc
├─ packages/
│  ├─ core-lib/
│  │  └─ package.json
│  ├─ ui-lib/
│  │  └─ package.json
│  └─ app-
│     └─ package.json

Key files:

• pnpm-workspace.yaml lists all packages.

  packages:
    - "packages/*"
  

• .npmrc enables workspaces and sets the store path.

  shamefully-hoist=false
  store-dir=~/.pnpm-store
  

• Each package.json declares only its direct dependencies. Transitive dependencies are never hoisted.

Trust & Data Boundaries

• Internal code – All workspace packages are trusted source code. They can import each other freely.
• External tarballs – npm registry packages are untrusted. pnpm downloads them into a content-addressable store and verifies their checksum.
• Node_modules layout – pnpm creates a node_modules/.pnpm directory where each dependency is a symlink to the store. Only declared dependencies appear; any missing import results in MODULE_NOT_FOUND.

Operational Checks

1. Reproducible install

   # Run on a clean machine or CI agent
   pnpm install --frozen-lockfile
   

   Exits non‑zero if pnpm-lock.yaml is out of sync. This guarantees that the lockfile is the source of truth.

2. CI filter selection

   # In CI, determine changed packages relative to base ref
   CHANGED=$(git diff --name-only $BASE_REF..HEAD | grep '^packages/' | cut -d'/' -f2 | uniq)
   # Run tests only for affected packages and their dependents
   pnpm --filter "${CHANGED}" test
   

   Ensure CI fetches at least the base commit and the full history of the packages/ directory. A shallow clone can silently skip tests.

3. Audit and why

   pnpm audit
   pnpm why 
   

   Use these tools to verify that no undeclared dependency is being used.

4. Store inspection

   pnpm store path
   

   Prints the absolute path to the local store. Useful for debugging disk‑usage or checksum errors.

Failure Modes

Scenario	Cause	Detection
Phantom dependency error	Package imports a transitive dependency that is not declared.	Runtime error MODULE_NOT_FOUND when running node or tests.
Store corruption	Checksum mismatch when reusing a store across incompatible pnpm versions.	pnpm install fails with checksum mismatch or ENOENT.
CI filter skips tests	Shallow clone missing base ref; --filter resolves to empty set.	CI job reports “No packages matched filter” or missing tests.
Duplicate installs	Different workspace protocol versions in the same repo.	Multiple copies of the same dependency appear in node_modules/.pnpm.

When to Redesign

• Need npm or yarn compatibility for a third‑party tool that only understands their layout.
• Legacy native tooling that requires hoisted node_modules to resolve node-gyp paths.
• Store size exceeds local disk capacity and you cannot share a remote store.
• Individual packages need independent release trains; a single lockfile forces a joint release cadence.

In such cases consider:

• Switching to npm workspaces or yarn workspaces with --hoist enabled.
• Using pnpm --lockfile-only per package and merging them manually.
• Configuring a remote pnpm store (e.g., pnpm store add --global) to offload disk usage.

Practical Verification Checklist

• [ ] pnpm install --frozen-lockfile passes on a fresh clone.
• [ ] pnpm --filter @mypkg/test test runs only the intended package.
• [ ] pnpm why shows direct dependency chain.
• [ ] pnpm store path points to a non‑empty directory and du -sh $(pnpm store path) is within limits.