0
# Workspace Management
1

2
Monorepo and workspace operations with filtering, recursive commands, and cross-package dependency management for complex multi-package projects.
3

4
## Capabilities
5

6
### Recursive Commands
7

8
Execute commands across all packages in a workspace with dependency awareness and parallel execution.
9

10
```bash { .api }
11
/**
12
 * Run commands recursively across workspace packages
13
 * Executes in topological order by default
14
 */
15
pnpm --recursive <command> [options]
16
pnpm -r <command> [options]
17
pnpm --multi <command> [options]
18
pnpm -m <command> [options]
19
```
20

21
**Options:**
22
- `--parallel` - Run commands in parallel instead of serial
23
- `--stream` - Stream output from parallel executions
24
- `--max-workers <number>` - Limit concurrent workers
25
- `--workspace-concurrency <number>` - Control workspace concurrency
26
- `--no-bail` - Continue execution despite failures
27
- `--reporter <type>` - Set output reporter for multi-package operations
28

29
**Usage Examples:**
30

31
```bash
32
# Install in all workspaces
33
pnpm -r install
34

35
# Build all packages in dependency order
36
pnpm -r build
37

38
# Test all packages in parallel
39
pnpm -r --parallel test
40

41
# Install with limited concurrency
42
pnpm -r --max-workers=2 install
43

44
# Continue testing despite failures
45
pnpm -r --no-bail test
46
```
47

48
### Package Filtering
49

50
Filter workspace packages using patterns, dependencies, and change detection for targeted operations.
51

52
```bash { .api }
53
/**
54
 * Filter workspace packages for targeted operations
55
 * Supports glob patterns, dependency filtering, and change detection
56
 */
57
pnpm --filter <pattern> <command> [options]
58
pnpm -F <pattern> <command> [options]
59
```
60

61
**Filter Patterns:**
62
- `package-name` - Exact package name match
63
- `@scope/*` - All packages in scope
64
- `*api*` - Packages containing "api" in name
65
- `frontend-*` - Packages starting with "frontend-"
66
- `./packages/*` - Packages in specific directory
67
- `{./packages/frontend}` - Specific package path
68

69
**Dependency Filtering:**
70
- `...package-name` - Package and all its dependencies
71
- `package-name...` - Package and all packages that depend on it
72
- `...package-name...` - Package, its dependencies, and dependents
73

74
**Change Detection:**
75
- `...[HEAD~1]` - Packages changed since HEAD~1
76
- `[HEAD~1]` - Only packages changed since HEAD~1 (not dependencies)
77
- `...[origin/main]` - Packages changed since origin/main
78

79
**Usage Examples:**
80

81
```bash
82
# Filter by name pattern
83
pnpm --filter "*api*" build
84
pnpm --filter "@myorg/*" test
85

86
# Filter by dependencies
87
pnpm --filter "...@myorg/core" build
88
pnpm --filter "@myorg/frontend..." test
89

90
# Filter by changes
91
pnpm --filter "...[HEAD~1]" test
92
pnpm --filter "[origin/main]" build
93

94
# Combine filters
95
pnpm --filter "@myorg/*" --filter "...[HEAD~1]" build
96
```
97

98
### Deploy Operations
99

100
Deploy workspace packages with production-optimized dependency resolution.
101

102
```bash { .api }
103
/**
104
 * Deploy workspace packages for production
105
 * Installs only production dependencies with optimized layout
106
 */
107
pnpm deploy <target-dir> [options]
108
```
109

110
**Options:**
111
- `--filter <pattern>` - Deploy specific packages only
112
- `--prod` - Deploy production dependencies only (default)
113
- `--dev` - Include development dependencies
114

115
**Usage Examples:**
116

117
```bash
118
# Deploy current package
119
pnpm deploy ../deploy/api
120

121
# Deploy with filtering
122
pnpm deploy --filter @myorg/api ../deploy/api
123

124
# Deploy multiple packages
125
pnpm deploy --filter "@myorg/{api,web}" ../deploy/
126
```
127

128
### Workspace Configuration
129

130
Configure workspace behavior through pnpm-workspace.yaml and package.json settings.
131

132
```yaml { .api }
133
# pnpm-workspace.yaml
134
packages:
135
  - 'packages/*'
136
  - 'apps/*' 
137
  - '!**/test/**'
138
```
139

140
**Workspace Root Management:**
141
- `--workspace-root`, `-w` - Include workspace root in operations
142
- `--include-workspace-root` - Include root when filtering
143
- `--ignore-workspace` - Ignore workspace configuration
144

145
**Usage Examples:**
146

147
```bash
148
# Include workspace root
149
pnpm -w add -D typescript
150

151
# Install in root and all packages
152
pnpm -r --include-workspace-root install
153

154
# Ignore workspace configuration
155
pnpm --ignore-workspace install
156
```
157

158
## Workspace Dependency Management
159

160
### Cross-Package Dependencies
161

162
Manage dependencies between workspace packages with workspace protocol.
163

164
```json { .api }
165
// package.json dependencies using workspace protocol
166
{
167
  "dependencies": {
168
    "@myorg/utils": "workspace:*",     // Any version from workspace
169
    "@myorg/core": "workspace:^1.0.0", // Version range from workspace  
170
    "@myorg/api": "workspace:~2.1.0"   // Specific range from workspace
171
  }
172
}
173
```
174

175
### Link Workspace Packages
176

177
Control how workspace packages are linked during development.
178

179
```bash { .api }
180
# Configuration options
181
--link-workspace-packages          # Link workspace packages (default: true)
182
--shared-workspace-lockfile       # Use single lockfile for workspace (default: true)
183
--save-workspace-protocol         # Save with workspace: protocol
184
```
185

186
**Usage Examples:**
187

188
```bash
189
# Add workspace dependency
190
pnpm add @myorg/utils --workspace
191

192
# Update workspace dependencies
193
pnpm update --recursive @myorg/core
194

195
# Install with workspace protocol
196
pnpm add @myorg/api --save-workspace-protocol
197
```
198

199
## Workspace Commands
200

201
### Workspace-Specific Install Behavior
202

203
Installation behavior differs in workspace environments with automatic recursive mode.
204

205
```bash { .api }
206
# Commands that auto-enable recursive mode in workspaces:
207
pnpm install    # Installs in root and all packages
208
pnpm import     # Imports lockfiles recursively  
209
pnpm dedupe     # Deduplicates across workspace
210
```
211

212
### Workspace Filtering Options
213

214
Advanced filtering for complex workspace scenarios.
215

216
```bash { .api }
217
# Workspace-aware filtering
218
--changed-files-ignore-pattern <pattern>  # Ignore files for change detection
219
--test-pattern <pattern>                  # Pattern for test files
220
--fail-if-no-match                       # Fail if no packages match filter
221
```
222

223
**Usage Examples:**
224

225
```bash
226
# Test only packages with changes, ignoring README updates
227
pnpm --filter "...[HEAD~1]" --changed-files-ignore-pattern "**/README.md" test
228

229
# Build packages matching pattern, fail if none found
230
pnpm --filter "@myorg/web-*" --fail-if-no-match build
231
```
232

233
### Workspace Script Execution
234

235
Execute scripts across workspace with various execution strategies.
236

237
```bash { .api }
238
# Serial execution (respects dependencies)
239
pnpm -r run build
240

241
# Parallel execution
242
pnpm -r --parallel run test
243

244
# Stream output from parallel runs
245
pnpm -r --parallel --stream run dev
246

247
# Limited concurrency
248
pnpm -r --parallel --max-workers=3 run build
249
```
250

251
## Workspace Analysis
252

253
### Package Relationships
254

255
Analyze package relationships and dependencies within workspace.
256

257
```bash { .api }
258
# Show workspace package tree
259
pnpm list --recursive
260

261
# Show why a package is included
262
pnpm why --recursive lodash
263

264
# Show outdated packages across workspace
265
pnpm outdated --recursive
266
```
267

268
### Workspace State
269

270
Commands for understanding workspace structure and state.
271

272
```bash { .api }
273
# List all workspace packages
274
pnpm list --recursive --depth=0
275

276
# Show workspace root
277
pnpm root
278

279
# Show workspace package locations
280
pnpm list --recursive --long
281
```
282

283
## Performance Optimization
284

285
### Concurrent Execution
286

287
Control concurrency for optimal performance in workspace operations.
288

289
```bash { .api }
290
# Control worker processes
291
--max-workers <number>              # Limit concurrent workers
292
--workspace-concurrency <number>    # Control workspace operation concurrency
293

294
# Execution strategies  
295
--parallel                          # Run in parallel
296
--stream                           # Stream output
297
--reporter append-only             # Optimized output for CI
298
```
299

300
### Selective Operations
301

302
Optimize workspace operations by targeting only necessary packages.
303

304
```bash { .api }
305
# Target changed packages only
306
pnpm --filter "...[HEAD~1]" build
307

308
# Target specific package groups
309
pnpm --filter "@myorg/{api,web}" test  
310

311
# Target by dependency relationships
312
pnpm --filter "...changed-package" build
313
```
314

315
## Build Management
316

317
### Approve Builds
318

319
Approve build permissions for packages with build scripts.
320

321
```bash { .api }
322
/**
323
 * Approve builds for packages
324
 * Manages build permissions for security
325
 */
326
pnpm approve-builds [options]
327
```
328

329
**Usage Examples:**
330

331
```bash
332
# Approve builds for current package
333
pnpm approve-builds
334

335
# Approve builds in workspace
336
pnpm approve-builds --recursive
337
```
338

339
### Ignored Builds
340

341
Manage packages that are ignored during build operations.
342

343
```bash { .api }
344
/**
345
 * Manage ignored builds
346
 * Controls which packages skip build scripts
347
 */
348
pnpm ignored-builds [options]
349
```
350

351
**Usage Examples:**
352

353
```bash
354
# Show ignored builds
355
pnpm ignored-builds
356

357
# Add package to ignored builds
358
pnpm ignored-builds add some-package
359
```
360

361
## Recursive Command Aliases
362

363
Alternative forms of recursive commands:
364

365
```bash { .api }
366
# Standard recursive syntax
367
pnpm --recursive <command>
368
pnpm -r <command>
369

370
# Multi command (alias for recursive)
371
pnpm --multi <command>
372
pnpm -m <command>
373

374
# Direct recursive command
375
pnpm recursive <command> 
376
pnpm multi <command>
377
pnpm m <command>
378
```