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## Named Catalogs
41 
42Create multiple catalogs for different scenarios:
43 
44```yaml
45packages:
46  - 'packages/*'
47 
48# Default catalog
49catalog:
50  lodash: ^4.17.21
51 
52# Named catalogs
53catalogs:
54  react17:
55    react: ^17.0.2
56    react-dom: ^17.0.2
57  
58  react18:
59    react: ^18.2.0
60    react-dom: ^18.2.0
61  
62  testing:
63    vitest: ^1.0.0
64    "@testing-library/react": ^14.0.0
65```
66 
67Reference named catalogs:
68 
69```json
70{
71  "dependencies": {
72    "react": "catalog:react18",
73    "react-dom": "catalog:react18"
74  },
75  "devDependencies": {
76    "vitest": "catalog:testing"
77  }
78}
79```
80 
81## Benefits
82 
831. **Single source of truth**: Update version in one place
842. **Consistency**: All packages use the same version
853. **Easy upgrades**: Change version once, affects entire workspace
864. **Type-safe**: TypeScript support in pnpm-workspace.yaml
87 
88## Catalog vs Overrides
89 
90| Feature | Catalogs | Overrides |
91|---------|----------|-----------|
92| Purpose | Define versions for direct dependencies | Force versions for any dependency |
93| Scope | Direct dependencies only | All dependencies (including transitive) |
94| Usage | `"pkg": "catalog:"` | Applied automatically |
95| Opt-in | Explicit per package.json | Global to workspace |
96 
97## Publishing with Catalogs
98 
99When publishing, `catalog:` references are replaced with actual versions:
100 
101```json
102// Before publish (source)
103{
104  "dependencies": {
105    "react": "catalog:"
106  }
107}
108 
109// After publish (published package)
110{
111  "dependencies": {
112    "react": "^18.2.0"
113  }
114}
115```
116 
117## Migration from Overrides
118 
119If you're using overrides for version consistency:
120 
121```yaml
122# Before (using overrides)
123overrides:
124  react: ^18.2.0
125  react-dom: ^18.2.0
126```
127 
128Migrate to catalogs for cleaner dependency management:
129 
130```yaml
131# After (using catalogs)
132catalog:
133  react: ^18.2.0
134  react-dom: ^18.2.0
135```
136 
137Then update package.json files to use `catalog:`.
138 
139## Best Practices
140 
1411. **Use default catalog** for commonly shared dependencies
1422. **Use named catalogs** for version variants (e.g., different React versions)
1433. **Keep catalog minimal** - only include shared dependencies
1444. **Combine with workspace protocol** for internal packages
145 
146```yaml
147catalog:
148  # External shared dependencies
149  lodash: ^4.17.21
150  zod: ^3.22.0
151 
152# Internal packages use workspace: protocol instead
153# "dependencies": { "@myorg/utils": "workspace:^" }
154```
155 
156<!-- 
157Source references:
158- https://pnpm.io/catalogs
159-->
160