Skip to content

chore(deps): adopt pnpm catalogs for single-version dependency policy #488

Description

@BleedingDev

Context

We want clearer dependency ownership and a single-version policy across the monorepo, especially after aligning the Next apps and enabling React Compiler.

Reference: https://antfu.me/posts/categorize-deps

The useful pattern from the article is to use pnpm catalogs / named catalogs in pnpm-workspace.yaml so workspace package manifests can say catalog:<name> instead of repeating literal versions everywhere. That gives us both centralized version control and dependency category context during reviews.

Scope

  • Introduce pnpm catalogs in pnpm-workspace.yaml for shared dependency families.
  • Start with high-churn / policy-sensitive families, for example:
    • frontend: React, React DOM, Next.js, React Compiler tooling, UI/runtime frontend packages.
    • build: TypeScript, Nx, Vite/Rolldown/SWC/build tooling.
    • lint: Biome, ESLint, Ultracite, lint plugins/configs.
    • test: Vitest, Playwright, Testing Library, MSW, test utilities.
    • types: @types/* packages where a single version policy matters.
    • backend: Medusa/Payload/server runtime packages if they benefit from centralization.
  • Replace duplicated literal versions in workspace package manifests with catalog references where safe.
  • Keep runtime dependencies vs devDependencies semantics intact; catalogs should categorize version ownership, not change install/runtime behavior.
  • Add a short dependency policy note explaining when to add a package to which catalog.
  • Consider adding tooling enforcement after migration, for example eslint-plugin-pnpm catalog rules or a lightweight custom check.

Non-Goals

Acceptance Criteria

  • Common duplicated dependency versions are represented through pnpm catalogs.
  • Package manifests use catalog: / catalog:<name> for migrated dependencies.
  • The lockfile is regenerated cleanly with pnpm.
  • Local workspace install validation passes with pnpm install --lockfile-only --frozen-lockfile after regeneration.
  • A short repo note documents the catalog categories and single-version policy.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions