Overview

Migrates Payload monorepo frompnpm.overrides topnpm catalogs for centralized dependency version management. This is Phase 1 of a two-phase migration, focusing on the 8 dependencies currently in overrides.

Key Changes

• Add pnpm catalog topnpm-workspace.yaml

  • 8 shared dependencies:copyfiles,cross-env,dotenv,graphql,mongodb-memory-server,react,react-dom,typescript

  Single source of truth for version management across workspace packages.

• Update 9 package.json files to usecatalog: protocol

  • Root, test, and 7 workspace packages now reference catalog instead of hardcoded versions
  • Removedpnpm.overrides block from root package.json

• Fix prod test setup for--ignore-workspace

  • setupProd.ts now resolvescatalog: entries to actual versions before runningpnpm i --ignore-workspace

  The--ignore-workspace flag ignores all workspace config including catalogs, so entries must be resolved beforehand.

Design Decisions

Catalog over overrides:pnpm.overrides forces versions on all transitive dependencies. Catalogs provide explicit opt-in version sharing viacatalog: protocol - cleaner and more intentional.

Minimal scope (Phase 1): Only migrated the 8 existing override dependencies. Phase 2 will audit and expand to commonly-duplicated deps likenext,drizzle-orm, etc.

peerDependencies unchanged: Packages like@payloadcms/ui keep wide version ranges (e.g.,"react": "^19.0.1 || ^19.1.2 || ^19.2.1") for consumer compatibility.

No external YAML parser:setupProd.ts uses simple string parsing to extract catalog entries, avoiding new dependencies.

Overall Flow

sequenceDiagram    participant Root as pnpm-workspace.yaml    participant Pkg as package.json files    participant Install as pnpm install    participant Pack as pnpm pack    Root->>Root: Define catalog versions    Pkg->>Pkg: Reference via "catalog:"    Install->>Root: Resolve catalog: to versions    Install->>Pkg: Install resolved versions    Pack->>Pkg: Replace catalog: with actual versions in tarball

References / Links

• pnpm Catalogs Documentation
• Supersedes closed PRbuild: use pnpm catalog #14408 (too messy to rebase)