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.
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.yamlso workspace package manifests can saycatalog:<name>instead of repeating literal versions everywhere. That gives us both centralized version control and dependency category context during reviews.Scope
pnpm-workspace.yamlfor shared dependency families.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.dependenciesvsdevDependenciessemantics intact; catalogs should categorize version ownership, not change install/runtime behavior.eslint-plugin-pnpmcatalog rules or a lightweight custom check.Non-Goals
Acceptance Criteria
catalog:/catalog:<name>for migrated dependencies.pnpm install --lockfile-only --frozen-lockfileafter regeneration.