From d4aba2edad2e98e5ccd4e14746618a0768313ea9 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 22 Jun 2026 10:39:23 +0000 Subject: [PATCH] docs(agents): catalog shared deps + enable pnpm catalogMode prefer --- AGENTS.md | 10 ++++++++++ pnpm-workspace.yaml | 4 ++++ 2 files changed, 14 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 8b7cc2eb37..87a5f48e77 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -409,6 +409,16 @@ pnpm add lodash-es pnpm add lodash ``` +**Catalog shared dependencies** + +When a dependency is used by more than one package (two or more), manage its version in the pnpm [catalog](https://pnpm.io/catalogs) instead of repeating a literal range in each `package.json`: + +1. Add the dependency and its version range to the default `catalog:` in `pnpm-workspace.yaml`. +2. Reference it from each `package.json` as `"dep-name": "catalog:"`. +3. If one package must stay on a different major than the rest, add a named catalog (e.g. `catalogs.date-fns-v2`) and reference it with `catalog:`. + +Leave `peerDependencies` compatibility ranges and `workspace:` protocol deps as they are — do not replace them with `catalog:`. `pnpm add` runs with `catalogMode: prefer` (set in `pnpm-workspace.yaml`), so adding a dependency that already exists in a catalog reuses the catalog version automatically. pnpm has no built-in "used N times" enforcement, so apply this rule whenever you add or move shared dependencies. + ### Formatting We use [oxfmt](https://oxc.rs/docs/formatter.html): diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index 9cf54e9f93..be52baddfa 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -73,6 +73,10 @@ catalogs: react-photo-album-v2: react-photo-album: ^2.4.1 +# When running `pnpm add`, reuse a dependency's catalog version automatically if +# it already exists in a catalog, so shared deps stay aligned on a single version. +catalogMode: prefer + minimumReleaseAge: 4320 minimumReleaseAgeExclude: