1---
2name: pnpm-catalogs
3description: Centralized dependency version management for workspaces
4---
5 
6# pnpm Catalogs
7 
8Catalogs provide a centralized way to manage dependency versions across a workspace. Define versions once, use everywhere.
9 
10## Basic Usage
11 
12Define a catalog in `pnpm-workspace.yaml`:
13 
14```yaml
15packages:
16  - 'packages/*'
17 
18catalog:
19  react: ^18.2.0
20  react-dom: ^18.2.0
21  typescript: ~5.3.0
22  vite: ^5.0.0
23```
24 
25Reference in `package.json` with `catalog:`:
26 
27```json
28{
29  "dependencies": {
30    "react": "catalog:",
31    "react-dom": "catalog:"
32  },
33  "devDependencies": {
34    "typescript": "catalog:",
35    "vite": "catalog:"
36  }
37}
38```
39 
40`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:`.
41 
42## Named Catalogs
43 
44Create multiple catalogs for different scenarios:
45 
46```yaml
47packages:
48  - 'packages/*'
49 
50# Default catalog
51catalog:
52  lodash: ^4.17.21
53 
54# Named catalogs
55catalogs:
56  react17:
57    react: ^17.0.2
58    react-dom: ^17.0.2
59  
60  react18:
61    react: ^18.2.0
62    react-dom: ^18.2.0
63  
64  testing:
65    vitest: ^1.0.0
66    "@testing-library/react": ^14.0.0
67```
68 
69Reference named catalogs:
70 
71```json
72{
73  "dependencies": {
74    "react": "catalog:react18",
75    "react-dom": "catalog:react18"
76  },
77  "devDependencies": {
78    "vitest": "catalog:testing"
79  }
80}
81```
82 
83## Keeping overrides in sync with a catalog
84 
85Reference a catalog from `overrides` so the version lives in exactly one place:
86 
87```yaml title="pnpm-workspace.yaml"
88catalog:
89  foo: ^1.0.0
90 
91overrides:
92  foo: 'catalog:'          # or catalog:<name>
93```
94 
95## Settings
96 
97```yaml title="pnpm-workspace.yaml"
98# How `pnpm add` interacts with the default catalog (v10.12+)
99catalogMode: manual        # manual (default) | prefer | strict
100# strict: only catalog versions allowed; prefer: fall back if no match
101cleanupUnusedCatalogs: true  # remove unused catalog entries on install (v10.15+)
102```
103 
104## Benefits
105 
1061. **Single source of truth**: Update version in one place
1072. **Consistency**: All packages use the same version
1083. **Easy upgrades**: Change version once, affects entire workspace
1094. **Fewer merge conflicts**: package.json files stay untouched on upgrades
110 
111## Catalog vs Overrides
112 
113| Feature | Catalogs | Overrides |
114|---------|----------|-----------|
115| Purpose | Define versions for direct dependencies | Force versions for any dependency |
116| Scope | Direct dependencies only | All dependencies (including transitive) |
117| Usage | `"pkg": "catalog:"` | Applied automatically |
118| Opt-in | Explicit per package.json | Global to workspace |
119 
120## Publishing with Catalogs
121 
122When publishing, `catalog:` references are replaced with actual versions:
123 
124```json
125// Before publish (source)
126{
127  "dependencies": {
128    "react": "catalog:"
129  }
130}
131 
132// After publish (published package)
133{
134  "dependencies": {
135    "react": "^18.2.0"
136  }
137}
138```
139 
140## Migration from Overrides
141 
142If you're using overrides for version consistency:
143 
144```yaml
145# Before (using overrides)
146overrides:
147  react: ^18.2.0
148  react-dom: ^18.2.0
149```
150 
151Migrate to catalogs for cleaner dependency management:
152 
153```yaml
154# After (using catalogs)
155catalog:
156  react: ^18.2.0
157  react-dom: ^18.2.0
158```
159 
160Then update package.json files to use `catalog:`. To migrate an existing workspace automatically:
161 
162```bash
163pnpx codemod pnpm/catalog
164```
165 
166## Best Practices
167 
1681. **Use default catalog** for commonly shared dependencies
1692. **Use named catalogs** for version variants (e.g., different React versions)
1703. **Keep catalog minimal** - only include shared dependencies
1714. **Combine with workspace protocol** for internal packages
172 
173```yaml
174catalog:
175  # External shared dependencies
176  lodash: ^4.17.21
177  zod: ^3.22.0
178 
179# Internal packages use workspace: protocol instead
180# "dependencies": { "@myorg/utils": "workspace:^" }
181```
182 
183<!-- 
184Source references:
185- https://pnpm.io/catalogs
186-->
187