chore(deps): move all dependencies to pnpm catalogs (AI-assisted) (#12696)

* chore(deps): use a pnpm catalog for dependencies shared by several packages (AI-assisted)

- Declare the 49 dependencies shared by several monorepo packages once,
  in the `catalog` of `pnpm-workspace.yaml`, and reference them with the
  `catalog:` protocol. The resolved versions in the lockfile don't change
- Dependency group members, template dependencies, pnpm overrides and
  peer dependencies keep explicit ranges, so syncpack keeps checking them
- Publish preview packages with `pkg-pr-new --pnpm`: `pnpm pack` replaces
  `catalog:` with versions, `npm pack` doesn't
- Document the catalog rules in the `dependencies` agent skill

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(deps): move all dependencies to pnpm catalogs, with a dev catalog for dev-only dependencies (AI-assisted)

- Every dependency of the monorepo packages now uses the pnpm catalogs:
  - The default catalog (`catalog:`) holds the dependencies used at
    runtime by at least one package
  - The `dev` catalog (`catalog:dev`) holds the dependencies only used as
    devDependencies
- Only the site templates, the pnpm overrides and the peer dependencies
  with intentionally broader ranges keep explicit versions
- `pnpm lint:syncpack` checks that dependencies use a catalog
- New `pnpm lint:catalogs` check, for what Syncpack can't check: catalog
  entries are in the right catalog, templates and overrides match the
  catalogs, and the members of each Dependabot group use the same version
- Dependency groups are now only declared in `.github/dependabot.yml`

The resolved packages of the lockfile don't change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* refactor(scripts): make lintCatalogs.js easier to review (AI-assisted)

Organize the script as a tree: main() gives the high-level picture, then the
data loading, one pure function per check, and the low-level helpers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(deps): enable pnpm catalogMode strict and catalogPrune, check unused catalog entries (AI-assisted)

- `catalogMode: strict`: `pnpm add` only accepts catalog versions, and adds
  new dependencies to the default catalog
- `catalogPrune: true`: `pnpm remove` removes the unused catalog entries
- `pnpm lint:catalogs` reports unused catalog entries: pnpm doesn't prune
  them when a package.json is edited manually

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* ci: type-check the website with min/max TypeScript versions through pnpm dlx (AI-assisted)

`pnpm add typescript@<version>` modified the workspace dependencies, and fails
with the new `catalogMode: strict` setting: the min version step adds
TypeScript to the catalog, then the max version step is outside its range.

Run the TypeScript compiler of the tested version with `pnpm dlx` instead,
without modifying package.json, the lockfile or the catalogs. Type
resolution still uses the workspace node_modules.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Author: slorber

.agents/skills/dependencies/SKILL.md

@@ -8,15 +8,39 @@ description: Add, remove or upgrade npm dependencies in the Docusaurus monorepo.
 ## Lockfile
 
 - Run `pnpm dedupe` after any lockfile change. CI fails if `pnpm-lock.yaml` is not deduplicated (`pnpm lint:deps`).
-- Run `pnpm lint:syncpack`: the same dependency must use the same version range in all packages.
 - Site template dependencies live in `packages/create-docusaurus/templates/`. Never edit `examples/`, it is CLI-generated.
 
+## Catalogs
+
+All the monorepo dependencies are declared in the [pnpm catalogs](https://pnpm.io/catalogs) of `pnpm-workspace.yaml`. Packages reference them with the catalog protocol instead of a version range:
+
+- `"catalog:"`: the default catalog, for dependencies used at runtime by at least one package (`dependencies`, `optionalDependencies` or `peerDependencies`).
+- `"catalog:dev"`: the dev catalog, for dependencies only used as `devDependencies`.
+
+Use pnpm commands to add and remove dependencies:
+
+- `pnpm add` only accepts catalog versions (`catalogMode: strict`), and adds new dependencies to the default catalog. Move dev-only dependencies to the dev catalog.
+- `pnpm remove` removes the catalog entries that are no longer used (`catalogPrune: true`). Manual `package.json` edits don't.
+
+Move a dev catalog entry to the default catalog as soon as a package uses it at runtime.
+
+Exceptions, keeping explicit versions:
+
+- The site templates, copied to user sites. Their versions must match the catalogs.
+- pnpm `overrides`. Their versions must match the catalogs.
+- Peer dependencies whose range intentionally differs from the catalog (see the ignored version groups of `.syncpackrc.ts`).
+
+Two checks enforce it:
+
+- `pnpm lint:syncpack`: dependencies must use a catalog.
+- `pnpm lint:catalogs` (`admin/scripts/lintCatalogs.js`): catalog entries are used and in the right catalog, templates and overrides match the catalogs, and dependency group members use the same version.
+
 ## Dependency groups
 
-Some packages must always use the same version. They are declared as groups in two places, which must stay in sync:
+Some packages must always use the same version. They are declared as `groups` in `.github/dependabot.yml`:
 
-- `.github/dependabot.yml` (`groups`): Dependabot upgrades them atomically in a single PR, instead of opening broken intermediate PRs.
-- `.syncpackrc.ts` (`dependencyGroups`): `pnpm lint:syncpack` fails if their versions differ.
+- Dependabot upgrades them atomically in a single PR, instead of opening broken intermediate PRs.
+- `pnpm lint:catalogs` fails if their catalog versions differ.
 
 Packages belong to a group when, for example:
 
@@ -29,6 +53,6 @@ Packages belong to a group when, for example:
 When you add a dependency, check whether it belongs to a group:
 
 - If an existing group already matches it (`@svgr/*` matches `@svgr/plugin-jsx`), there is nothing to do.
-- Otherwise, add it to the matching group, or create a new group, in both files. Follow the existing groups: one group per package family, with a comment explaining why the packages must stay in sync.
+- Otherwise, add it to the matching group, or create a new group. Follow the existing groups: one group per package family, with a comment explaining why the packages must stay in sync.
 
 Do the same when a Dependabot PR can't pass CI on its own because a related package wasn't upgraded with it.

.github/dependabot.yml

@@ -34,7 +34,7 @@ updates:
       semver-minor-days: 8
       semver-patch-days: 8
     # Packages that must be upgraded atomically in a single PR
-    # Keep in sync with the dependencyGroups of .syncpackrc.ts
+    # pnpm lint:catalogs checks that the catalog versions of each group match
     groups:
       # Released in lockstep, mixing versions breaks typechecking
       # See https://github.com/facebook/docusaurus/pull/12634

.github/workflows/continuous-releases.yml

@@ -59,4 +59,5 @@ jobs:
           node ./packages/create-docusaurus/bin/index.js template/docusaurus-classic-ts classic --typescript -p npm
 
       - name: Release
-        run: pnpm pkg-pr-new publish './packages/*' --template './template/*' --compact --comment=off
+        # --pnpm: use pnpm pack, which replaces the catalog: protocol with versions
+        run: pnpm pkg-pr-new publish './packages/*' --template './template/*' --compact --comment=off --pnpm

.github/workflows/lint.yml

@@ -54,6 +54,8 @@ jobs:
             run: pnpm lint:spelling
           - name: Syncpack
             run: pnpm lint:syncpack
+          - name: Catalogs
+            run: pnpm lint:catalogs
           - name: Check deduped pnpm-lock.yaml
             run: pnpm lint:deps
           - name: Knip

.github/workflows/tests-windows.yml

@@ -70,18 +70,16 @@ jobs:
         # see https://github.com/facebook/docusaurus/pull/10486
         run: pnpm --filter website typecheck
 
+      # The TypeScript compiler of the tested version runs with pnpm dlx,
+      # without modifying the workspace dependencies (package.json, catalogs)
       - name: TypeCheck website - min version - v6.0
-        # We call the "typescript" package compiler explicitly, because the
-        # root "tsc" bin comes from "@typescript/native" (pinned TS 7)
         run: |
-          pnpm add typescript@6.0 --save-exact -D -w --ignore-scripts
-          node node_modules/typescript/bin/tsc --version
-          node node_modules/typescript/bin/tsc --project website/tsconfig.json
+          pnpm dlx --package=typescript@6.0 tsc --version
+          pnpm dlx --package=typescript@6.0 tsc --project website/tsconfig.json
 
       - name: TypeCheck website - max version - Latest
         # For latest TS there are often lib check errors, so we disable it
         # Details: https://github.com/facebook/docusaurus/pull/10486
         run: |
-          pnpm add typescript@latest --save-exact -D -w --ignore-scripts
-          node node_modules/typescript/bin/tsc --version
-          node node_modules/typescript/bin/tsc --project website/tsconfig.skipLibCheck.json
+          pnpm dlx --package=typescript@latest tsc --version
+          pnpm dlx --package=typescript@latest tsc --project website/tsconfig.skipLibCheck.json

.github/workflows/tests.yml

@@ -67,18 +67,16 @@ jobs:
         # see https://github.com/facebook/docusaurus/pull/10486
         run: pnpm --filter website typecheck
 
+      # The TypeScript compiler of the tested version runs with pnpm dlx,
+      # without modifying the workspace dependencies (package.json, catalogs)
       - name: TypeCheck website - min version - v6.0
-        # We call the "typescript" package compiler explicitly, because the
-        # root "tsc" bin comes from "@typescript/native" (pinned TS 7)
         run: |
-          pnpm add typescript@6.0 --save-exact -D -w --ignore-scripts
-          node node_modules/typescript/bin/tsc --version
-          node node_modules/typescript/bin/tsc --project website/tsconfig.json
+          pnpm dlx --package=typescript@6.0 tsc --version
+          pnpm dlx --package=typescript@6.0 tsc --project website/tsconfig.json
 
       - name: TypeCheck website - max version - Latest
         # For latest TS there are often lib check errors, so we disable it
         # Details: https://github.com/facebook/docusaurus/pull/10486
         run: |
-          pnpm add typescript@latest --save-exact -D -w --ignore-scripts
-          node node_modules/typescript/bin/tsc --version
-          node node_modules/typescript/bin/tsc --project website/tsconfig.skipLibCheck.json
+          pnpm dlx --package=typescript@latest tsc --version
+          pnpm dlx --package=typescript@latest tsc --project website/tsconfig.skipLibCheck.json

.syncpackrc.ts

@@ -20,27 +20,6 @@ export default {
     'packages/create-docusaurus/templates/*/package.json',
   ],
 
-  // Packages that must use the same version, treated as a single dependency
-  // Keep in sync with the groups of .github/dependabot.yml
-  dependencyGroups: [
-    {aliasName: 'svgr', dependencies: ['@svgr/**']},
-    {aliasName: 'workbox', dependencies: ['workbox-*']},
-    {aliasName: 'rsdoctor', dependencies: ['@rsdoctor/**']},
-    {aliasName: 'react', dependencies: ['react', 'react-dom']},
-    {
-      aliasName: 'react-types',
-      dependencies: ['@types/react', '@types/react-dom'],
-    },
-    {
-      aliasName: 'react-router',
-      dependencies: ['react-router', 'react-router-dom'],
-    },
-    {
-      aliasName: 'typescript-eslint',
-      dependencies: ['typescript-eslint', '@typescript-eslint/**'],
-    },
-  ],
-
   semverGroups: [
     {
       label: 'Use ~ for TypeScript monorepo root and init templates',
@@ -72,9 +51,9 @@ export default {
         '@docusaurus/types',
       ],
       dependencies: [
-        // Aliases from dependencyGroups
         'react',
-        'react-types',
+        'react-dom',
+        '@types/react',
         '@types/react-router-config',
         '@types/react-router-dom',
       ],
@@ -126,6 +105,23 @@ export default {
       pinVersion: 'workspace:*',
     },
 
-    // Default: all remaining dependencies — highest version wins (syncpack default)
+    {
+      label:
+        "Templates can't use catalogs, lintCatalogs.js checks their versions against the catalogs",
+      packages: [
+        'docusaurus-2-classic-template',
+        'docusaurus-2-classic-typescript-template',
+      ],
+      isIgnored: true,
+    },
+
+    {
+      // Runtime dependencies use the default catalog ("catalog:")
+      // Dev-only dependencies use the dev catalog ("catalog:dev")
+      // lintCatalogs.js checks the catalogs content
+      label: 'All the other dependencies must use a pnpm catalog',
+      dependencyTypes: ['prod', 'dev', 'peer'],
+      policy: 'catalog',
+    },
   ],
 } satisfies RcFile;

AGENTS.md

@@ -55,7 +55,7 @@ The main CLI commands available
 - `pnpm build:packages` - Build all monorepo packages
 - `pnpm watch` - Incremental build of monorepo packages with file watchers
 - `pnpm format` - Format code with oxfmt
-- `pnpm lint` - Run all the lint checks that CI runs (ESLint + Stylelint + spell check + Syncpack + dedupe check + Knip + formatting check)
+- `pnpm lint` - Run all the lint checks that CI runs (ESLint + Stylelint + spell check + Syncpack + catalogs check + dedupe check + Knip + formatting check)
 - `pnpm dedupe` - Deduplicate `pnpm-lock.yaml` dependencies, run it after any lockfile change
 - `pnpm test` - Run all tests using Vitest
 - `pnpm clear` - Clean all build artifacts and caches
@@ -87,7 +87,8 @@ Update Vitest failing snapshots with the `-u` option. Do not blindly update snap
 - `pnpm lint:js` - ESLint for JS/TS files
 - `pnpm lint:style` - Stylelint for CSS files
 - `pnpm lint:spelling` - CSpell for spell checking
-- `pnpm lint:syncpack` - Syncpack to check consistent dependency versions across packages
+- `pnpm lint:syncpack` - Syncpack to check that dependencies use the pnpm catalogs
+- `pnpm lint:catalogs` - Check the content of the pnpm catalogs
 - `pnpm lint:knip` - Knip to find unused files, exports and dependencies (config in `knip.config.ts`)
 - `pnpm lint:deps` - Check that `pnpm-lock.yaml` is deduplicated (`pnpm dedupe --check`)
 - Add `:fix` suffix to auto-fix issues (e.g., `pnpm lint:js:fix`)