docs: require the pnpm catalog for shared deps + enable catalogMode#1374
docs: require the pnpm catalog for shared deps + enable catalogMode#1374stipsan wants to merge 2 commits into
Conversation
|
| Name | Type |
|---|---|
| @sanity/assist | Patch |
| sanity-plugin-internationalized-array | Patch |
| @sanity/document-internationalization | Patch |
| @sanity/sfcc | Patch |
Click here to learn what changesets are, and how to add one.
Click here if you're a maintainer who wants to add a changeset to this PR
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
There was a problem hiding this comment.
Pull request overview
Documents and nudges consistent use of pnpm catalogs for shared dependency versions, to prevent version drift across packages in the monorepo.
Changes:
- Adds
catalogMode: prefertopnpm-workspace.yamlsopnpm addreuses existing catalog versions automatically. - Updates
AGENTS.mdwith a guideline: dependencies used by 2+ packages should be versioned via the pnpm catalog and referenced withcatalog:.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| pnpm-workspace.yaml | Enables catalogMode: prefer to reduce accidental divergence from cataloged dependency versions. |
| AGENTS.md | Documents the “shared deps go in the catalog” policy and how to use default vs named catalogs. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| 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:<name>`. |
…ency-policy-a424 # Conflicts: # pnpm-workspace.yaml
| --- | ||
| '@sanity/assist': patch | ||
| "@sanity/assist": patch | ||
| --- |
What & why
Follow-up to the catalog migration: make "shared deps live in the catalog" the standing policy so the catalog doesn't drift back over time.
Two complementary pieces:
AGENTS.mdguideline — documents the rule: when a dependency is used by more than one package (two or more), manage its version in the pnpmcatalog:and reference it withcatalog:from eachpackage.json, with named catalogs for cases that need a different major (shared studio peers use the existingcatalog:peernamed catalog).pnpm-workspace.yaml→catalogMode: prefer— the native pnpm setting. Withprefer,pnpm add <dep>automatically reuses a dependency's catalog version when it already exists in a catalog, instead of writing a fresh literal range.Merge note
mainalready landedcatalogMode: prefer(and the reorganized nearby settings /minimumReleaseAge: 1440) while this PR was open. The merge conflict inpnpm-workspace.yamlwas a simple overlap: both sides wantedcatalogMode: prefer. Resolution kept main's surrounding settings and retained a short comment explaining whycatalogModeis set. The AGENTS.md "Catalog shared dependencies" section was also tweaked post-merge so it doesn't contradict main's newercatalog:peerpeer-deps guidance.Why not enforce purely in pnpm?
pnpm has no native "used N times" threshold.
catalogModeonly governspnpm add:prefer(chosen) — reuse catalog versions when present; fall back to a direct dep otherwise. Non-disruptive.strict— error if a dep isn't in the catalog. Too aggressive for a monorepo with many single-use deps.So the threshold rule itself is documented in
AGENTS.md, withcatalogMode: preferas the automated nudge.Notes
Verification
pnpm install --frozen-lockfile— succeeds after merge.