Skip to content

chore/support-catalogs-2 - #1

Draft
gevalo1 wants to merge 8 commits into
mainfrom
chore/support-catalogs-2
Draft

chore/support-catalogs-2#1
gevalo1 wants to merge 8 commits into
mainfrom
chore/support-catalogs-2

Conversation

@gevalo1

@gevalo1 gevalo1 commented Aug 3, 2026

Copy link
Copy Markdown

Closes 1707. Supersedes 1933

Note: AI-assisted (Claude Opus 5) while writing, human-reviewed and human-tested.

Problem

Catalogs let a workspace declare a version range once and reference it from many
packages through the catalog: protocol. Changesets doesn't understand the
protocol today, which shows up in three places:

  1. catalog: is a protocol range, so a workspace package referenced through one
    is treated as invalid by getDependencyGraph, which prints "must depend on
    the current version of ...".
  2. Releasing a package that a catalog points at leaves the catalog entry stale.
    Nothing updates it, so the workspace keeps installing the old version.
  3. Updating a catalog entry marks nothing as changed. Editing the same range in
    a package's own package.json does mark that package as changed, because
    change detection is file based and the file lives inside the package. A
    catalog lives at the workspace root and belongs to no package in particular.

What this does

Adds @changesets/catalogs, which knows where each package manager keeps its
catalogs, how to resolve a catalog: reference, and how to write an updated
range back:

Package manager Location
pnpm catalog / catalogs in pnpm-workspace.yaml
Yarn catalog / catalogs in .yarnrc.yml
Bun catalog / catalogs in package.json, at the root or under workspaces

Both the default catalog (catalog:, also spelled catalog:default) and named
catalogs (catalog:react18) are supported.

On top of that:

  • Resolution. Ranges are resolved wherever Changesets reads a dependency
    range — the dependency graph, dependent bumps, and changelog entries — so a
    catalog: reference behaves exactly as the range written out in full would.
  • Versioning. Releasing a package that a catalog points at rewrites the
    catalog entry and keeps its range style (^1.0.0 becomes ^2.0.0). The
    packages referencing it keep saying catalog:. Entries that no package in the
    workspace references are left alone, matching what bun update does.
  • Change detection. An updated catalog entry counts as a change to every
    package referencing it, for changeset add and changeset status. New
    detectCatalogChanges config option, default true, to opt out.

Notes for review

  • The YAML and JSON writers edit in place using node ranges rather than
    re-serialising, so comments, quote style and ordering in pnpm-workspace.yaml
    survive untouched. Same approach as the existing editJson.
  • Packages.catalogs is optional. Making it required would enforce it at the
    type level, but it breaks assembleReleasePlan(changesets, await getPackages(cwd), config)
    for external consumers, which is the usage documented in
    @changesets/get-dependents-graph's README. Entry points that build a graph or
    a release plan call a small withCatalogs helper instead.
  • pack and publish need nothing extra — pnpm, Yarn and Bun each replace
    catalog: during their own pack step.

The commits are split by layer, so each is reviewable on its own.

@gevalo1
gevalo1 changed the base branch from chore/support-catalogs to main August 3, 2026 08:36
@gevalo1
gevalo1 force-pushed the chore/support-catalogs-2 branch 2 times, most recently from 04b1379 to 8dfc0a6 Compare August 4, 2026 07:53
@gevalo1
gevalo1 force-pushed the chore/support-catalogs-2 branch from 8dfc0a6 to 9f22a5e Compare August 13, 2026 11:51
@gevalo1
gevalo1 force-pushed the chore/support-catalogs-2 branch from 9f22a5e to f68ecd3 Compare August 13, 2026 13:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant