Monorepo Management with PNPM

Best practices for managing large PNPM monorepos following Constructive conventions. Covers workspace configuration, dependency management, selective builds, and package organization.

When to Apply

Use this skill when:

•Managing a multi-package repository
•Configuring workspace dependencies
•Setting up selective builds and filtering
•Organizing packages in a large codebase
•Configuring lerna versioning strategies

Workspace Configuration

pnpm-workspace.yaml

Define package locations:

yaml

packages:
  - 'packages/*'

For larger projects with multiple directories:

yaml

packages:
  - 'packages/*'
  - 'pgpm/*'
  - 'graphql/*'
  - 'postgres/*'
  - 'apps/*'
  - 'libs/*'

Root package.json

json

{
  "name": "my-workspace",
  "version": "0.0.1",
  "private": true,
  "scripts": {
    "build": "pnpm -r run build",
    "test": "pnpm -r run test",
    "lint": "pnpm -r run lint",
    "clean": "pnpm -r run clean",
    "deps": "pnpm up -r -i -L"
  }
}

Key points:

•Root is always private: true
•Scripts use pnpm -r for recursive execution
•deps script for interactive dependency updates

Workspace Dependencies

workspace:* Protocol

Reference internal packages:

json

{
  "dependencies": {
    "my-utils": "workspace:*"
  }
}

When published, workspace:* is replaced with the actual version.

Dependency Types

Protocol	Behavior
`workspace:*`	Latest version in workspace
`workspace:^`	Compatible version range
`workspace:~`	Patch version range

Adding Workspace Dependencies

bash

# Add workspace dependency
pnpm add my-utils --filter my-app --workspace

# Add external dependency to specific package
pnpm add lodash --filter my-app

# Add dev dependency to root
pnpm add -D typescript -w

Filtering and Selective Builds

--filter Flag

Run commands on specific packages:

bash

# Single package
pnpm --filter my-app run build

# Multiple packages
pnpm --filter my-app --filter my-utils run build

# Glob patterns
pnpm --filter "my-*" run build

# Package and its dependencies
pnpm --filter my-app... run build

# Package and its dependents
pnpm --filter ...my-utils run build

# Exclude packages
pnpm --filter "!my-legacy" run build

Dependency-Aware Builds

bash

# Build package and all its dependencies
pnpm --filter my-app... run build

# Build only dependencies (not the package itself)
pnpm --filter "my-app^..." run build

# Build dependents (packages that depend on this)
pnpm --filter "...my-utils" run build

Changed Packages

bash

# Packages changed since main
pnpm --filter "...[origin/main]" run build

# Packages changed in last commit
pnpm --filter "...[HEAD~1]" run build

Package Organization

Directory Structure

Organize by domain or type:

code

my-workspace/
├── packages/           # Shared utilities
│   ├── utils/
│   ├── types/
│   └── config/
├── apps/               # Applications
│   ├── web/
│   └── api/
├── libs/               # Domain libraries
│   ├── auth/
│   └── database/
├── pgpm/               # PGPM modules (if hybrid)
│   └── migrations/
├── pnpm-workspace.yaml
├── lerna.json
└── package.json

Naming Conventions

Type	Convention	Example
Scoped packages	`@org/package-name`	`@myorg/utils`
Internal packages	`package-name`	`my-utils`
Apps	`app-name`	`web-app`

Lerna Configuration

Independent Versioning

Each package versioned separately:

json

{
  "$schema": "node_modules/lerna/schemas/lerna-schema.json",
  "version": "independent",
  "npmClient": "pnpm",
  "command": {
    "publish": {
      "allowBranch": "main",
      "conventionalCommits": true
    }
  }
}

Best for: utility libraries with different release cycles.

Fixed Versioning

All packages share same version:

json

{
  "$schema": "node_modules/lerna/schemas/lerna-schema.json",
  "version": "1.0.0",
  "npmClient": "pnpm",
  "command": {
    "publish": {
      "allowBranch": "main",
      "conventionalCommits": true
    }
  }
}

Best for: tightly coupled packages that release together.

Versioning Commands

bash

# Version changed packages
pnpm lerna version

# Version with specific bump
pnpm lerna version patch
pnpm lerna version minor
pnpm lerna version major

# Preview without changes
pnpm lerna version --no-git-tag-version --no-push

Dependency Management

Update Dependencies

bash

# Interactive update all packages
pnpm up -r -i -L

# Update specific dependency everywhere
pnpm up lodash -r

# Update to latest
pnpm up lodash@latest -r

Check for Outdated

bash

pnpm outdated -r

Dedupe Dependencies

bash

pnpm dedupe

Build Optimization

Parallel Builds

PNPM runs in parallel by default. Control concurrency:

bash

# Limit concurrent tasks
pnpm -r --workspace-concurrency=4 run build

Topological Order

Dependencies are built first automatically:

bash

# Builds in dependency order
pnpm -r run build

Caching

Use turbo or nx for build caching in large repos:

json

{
  "scripts": {
    "build": "turbo run build"
  }
}

CI/CD Patterns

Install Dependencies

bash

pnpm install --frozen-lockfile

Build Changed Packages

bash

# Build packages changed since main
pnpm --filter "...[origin/main]" run build

Test Changed Packages

bash

pnpm --filter "...[origin/main]" run test

Publish Workflow

bash

# Version and publish
pnpm lerna version --yes
pnpm lerna publish from-package --yes

Common Commands Reference

Command	Description
`pnpm install`	Install all dependencies
`pnpm -r run build`	Build all packages
`pnpm -r run test`	Test all packages
`pnpm --filter <pkg> run <cmd>`	Run command in specific package
`pnpm --filter <pkg>... run <cmd>`	Run in package and dependencies
`pnpm add <dep> --filter <pkg>`	Add dependency to package
`pnpm add <dep> -w`	Add dependency to root
`pnpm up -r -i -L`	Interactive dependency update
`pnpm lerna version`	Version packages
`pnpm lerna publish`	Publish packages

Hybrid Workspaces

Some repos (like Constructive) have both PNPM packages and PGPM modules:

yaml

# pnpm-workspace.yaml
packages:
  - 'packages/*'      # TypeScript packages
  - 'pgpm/*'          # PGPM CLI and tools
  - 'postgres/*'      # PostgreSQL utilities

The root may also have a pgpm.json for SQL module configuration.

Troubleshooting

Dependency Resolution Issues

bash

# Clear cache and reinstall
pnpm store prune
rm -rf node_modules
pnpm install

Workspace Link Issues

bash

# Check workspace links
pnpm why <package-name>

Build Order Issues

bash

# Verify dependency graph
pnpm list -r --depth=0

Best Practices

•Keep root private: Never publish the root package
•Use workspace protocol: Always workspace:* for internal deps
•Consistent structure: Same directory layout across packages
•Shared config: Extend root tsconfig.json, eslint.config.js
•Filter in CI: Only build/test changed packages
•Lock file: Always commit pnpm-lock.yaml
•Dedupe regularly: Run pnpm dedupe periodically
•Document dependencies: Clear README for each package

References

•Related skill: pnpm-workspace for workspace setup
•Related skill: pnpm-publishing for publishing workflow
•Related skill: pgpm-workspace for SQL module workspaces