Setting the file. One moment.
Subchapter 6.9
references/features-catalogs.mdMarkdown4 KBView on GitHub
Catalogs provide a centralized way to manage dependency versions across a workspace. Define versions once, use everywhere.
Define a catalog in pnpm-workspace.yaml:
packages:
- 'packages/*'
catalog:
react: ^18.2.0
react-dom: ^18.2.0
typescript: ~5.3.0
vite: ^5.0.0Reference in package.json with catalog::
{
"dependencies": {
"react": "catalog:",
"react-dom": "catalog:"
},
"devDependencies": {
"typescript": "catalog:",
"vite": "catalog:"
}
}catalog: is shorthand for catalog:default. The catalog: protocol is valid in package.json dependencies, devDependencies, peerDependencies, and optionalDependencies, plus in overrides inside pnpm-workspace.yaml. It also works on the CLI: pnpm add react@catalog: and pnx shx@catalog:.
Create multiple catalogs for different scenarios:
packages:
- 'packages/*'
# Default catalog
catalog:
lodash: ^4.17.21
# Named catalogs
catalogs:
react17:
react: ^17.0.2
react-dom: ^17.0.2
react18:
react: ^18.2.0
react-dom: ^18.2.0
testing:
vitest: ^1.0.0
"@testing-library/react": ^14.0.0Reference named catalogs:
{
"dependencies": {
"react": "catalog:react18",
"react-dom": "catalog:react18"
},
"devDependencies": {
"vitest": "catalog:testing"
}
}Reference a catalog from overrides so the version lives in exactly one place:
catalog:
foo: ^1.0.0
overrides:
foo: 'catalog:' # or catalog:<name># How `pnpm add` interacts with the default catalog (v10.12+)
catalogMode: manual # manual (default) | prefer | strict
# strict: only catalog versions allowed; prefer: fall back if no match
cleanupUnusedCatalogs: true # remove unused catalog entries on install (v10.15+)| Feature | Catalogs | Overrides |
|---|---|---|
| Purpose | Define versions for direct dependencies | Force versions for any dependency |
| Scope | Direct dependencies only | All dependencies (including transitive) |
| Usage | "pkg": "catalog:" | Applied automatically |
| Opt-in | Explicit per package.json | Global to workspace |
When publishing, catalog: references are replaced with actual versions:
// Before publish (source)
{
"dependencies": {
"react": "catalog:"
}
}
// After publish (published package)
{
"dependencies": {
"react": "^18.2.0"
}
}If you’re using overrides for version consistency:
# Before (using overrides)
overrides:
react: ^18.2.0
react-dom: ^18.2.0Migrate to catalogs for cleaner dependency management:
# After (using catalogs)
catalog:
react: ^18.2.0
react-dom: ^18.2.0Then update package.json files to use catalog:. To migrate an existing workspace automatically:
pnpx codemod pnpm/catalogcatalog:
# External shared dependencies
lodash: ^4.17.21
zod: ^3.22.0
# Internal packages use workspace: protocol instead
# "dependencies": { "@myorg/utils": "workspace:^" }