0
# Workspace Management
1

2
Commands for managing monorepos and workspaces, enabling multiple packages to be developed together in a single repository.
3

4
## Capabilities
5

6
### Workspace Information
7

8
Get information about workspaces in the current project.
9

10
```bash { .api }
11
yarn workspaces info [options]
12

13
# Options:
14
--json                   # Output in JSON format
15
```
16

17
**Usage Examples:**
18

19
```bash
20
# Show workspace information
21
yarn workspaces info
22

23
# Get JSON output for programmatic use
24
yarn workspaces info --json
25
```
26

27
**Output Format:**
28
```json
29
{
30
  "@company/package-a": {
31
    "location": "packages/package-a",
32
    "workspaceDependencies": ["@company/shared"],
33
    "mismatchedWorkspaceDependencies": []
34
  },
35
  "@company/package-b": {
36
    "location": "packages/package-b", 
37
    "workspaceDependencies": ["@company/shared"],
38
    "mismatchedWorkspaceDependencies": []
39
  },
40
  "@company/shared": {
41
    "location": "packages/shared",
42
    "workspaceDependencies": [],
43
    "mismatchedWorkspaceDependencies": []
44
  }
45
}
46
```
47

48
### Run Commands in All Workspaces
49

50
Execute commands across all workspace packages.
51

52
```bash { .api }
53
yarn workspaces run <command>
54
```
55

56
**Usage Examples:**
57

58
```bash
59
# Run script in all workspaces
60
yarn workspaces run build
61
yarn workspaces run test
62
yarn workspaces run lint
63

64
# Run with yarn run (for scripts defined in package.json)
65
yarn workspaces run start
66
yarn workspaces run clean
67

68
# Commands run in parallel by default
69
yarn workspaces run test --coverage
70
```
71

72
**Execution Order:**
73
- Commands run in dependency order when workspace dependencies exist
74
- Independent packages run in parallel
75
- If package A depends on package B, B builds before A
76

77
### Run Commands in Specific Workspace
78

79
Execute commands in a specific workspace package.
80

81
```bash { .api }
82
yarn workspace <workspace-name> <command>
83
```
84

85
**Usage Examples:**
86

87
```bash
88
# Run script in specific workspace
89
yarn workspace @company/package-a build
90
yarn workspace @company/package-a test
91

92
# Add dependency to specific workspace
93
yarn workspace @company/package-a add lodash
94
yarn workspace @company/package-a add --dev jest
95

96
# Remove dependency from specific workspace  
97
yarn workspace @company/package-a remove lodash
98

99
# Install dependencies for specific workspace
100
yarn workspace @company/package-a install
101

102
# Run arbitrary commands
103
yarn workspace @company/package-a exec ls -la
104
yarn workspace @company/package-a node scripts/custom.js
105
```
106

107
## Workspace Configuration
108

109
### Root package.json Setup
110

111
```json
112
{
113
  "name": "my-monorepo",
114
  "private": true,
115
  "workspaces": [
116
    "packages/*",
117
    "apps/*",
118
    "tools/*"
119
  ],
120
  "devDependencies": {
121
    "jest": "^29.0.0",
122
    "eslint": "^8.0.0"
123
  },
124
  "scripts": {
125
    "build": "yarn workspaces run build",
126
    "test": "yarn workspaces run test",
127
    "lint": "yarn workspaces run lint",
128
    "clean": "yarn workspaces run clean"
129
  }
130
}
131
```
132

133
### Workspace Package Structure
134

135
```
136
my-monorepo/
137
├── package.json (root)
138
├── yarn.lock (shared)
139
├── packages/
140
│   ├── package-a/
141
│   │   ├── package.json
142
│   │   └── src/
143
│   ├── package-b/
144
│   │   ├── package.json
145
│   │   └── src/
146
│   └── shared/
147
│       ├── package.json
148
│       └── src/
149
└── apps/
150
    └── web-app/
151
        ├── package.json
152
        └── src/
153
```
154

155
### Individual Workspace package.json
156

157
```json
158
{
159
  "name": "@company/package-a",
160
  "version": "1.0.0",
161
  "main": "dist/index.js",
162
  "scripts": {
163
    "build": "tsc",
164
    "test": "jest",
165
    "clean": "rimraf dist"
166
  },
167
  "dependencies": {
168
    "@company/shared": "1.0.0",
169
    "lodash": "^4.17.21"
170
  },
171
  "devDependencies": {
172
    "typescript": "^4.8.0"
173
  }
174
}
175
```
176

177
## Workspace Dependencies
178

179
### Cross-Workspace Dependencies
180

181
```bash
182
# Add workspace dependency
183
yarn workspace @company/package-a add @company/shared
184

185
# Add external dependency
186
yarn workspace @company/package-a add react
187

188
# Add dev dependency
189
yarn workspace @company/package-a add --dev @types/react
190
```
191

192
**package.json Result:**
193
```json
194
{
195
  "dependencies": {
196
    "@company/shared": "1.0.0",
197
    "react": "^18.0.0"
198
  },
199
  "devDependencies": {
200
    "@types/react": "^18.0.0"
201
  }
202
}
203
```
204

205
### Dependency Hoisting
206

207
Yarn automatically hoists shared dependencies to the root:
208

209
```
210
node_modules/           # Root node_modules (hoisted)
211
├── react/             # Shared by multiple workspaces
212
├── lodash/            # Shared dependency
213
└── @company/
214
    ├── package-a/     # Symlink to packages/package-a
215
    ├── package-b/     # Symlink to packages/package-b
216
    └── shared/        # Symlink to packages/shared
217
```
218

219
### Version Conflicts
220

221
When workspaces require different versions:
222

223
```json
224
// package-a/package.json
225
{
226
  "dependencies": {
227
    "lodash": "^4.17.21"
228
  }
229
}
230

231
// package-b/package.json  
232
{
233
  "dependencies": {
234
    "lodash": "^3.10.1"
235
  }
236
}
237
```
238

239
Result:
240
```
241
node_modules/
242
├── lodash/            # Version 4.17.21 (most common)
243
└── package-b/
244
    └── node_modules/
245
        └── lodash/    # Version 3.10.1 (specific to package-b)
246
```
247

248
## Advanced Workspace Commands
249

250
### Selective Operations
251

252
Using yarn v2+ syntax (if available):
253

254
```bash
255
# Run command on packages matching pattern
256
yarn workspaces foreach --include="@company/*" run build
257

258
# Run command excluding certain packages
259
yarn workspaces foreach --exclude="@company/internal-*" run test
260

261
# Run only on packages that changed
262
yarn workspaces foreach --since="origin/main" run build
263

264
# Run with specific concurrency
265
yarn workspaces foreach --parallel run build
266
```
267

268
### Dependency Management
269

270
```bash
271
# Add dependency to root (shared across workspaces)
272
yarn add --dev eslint
273

274
# Add dependency to all workspaces
275
yarn workspaces run add lodash
276

277
# Update dependencies in all workspaces
278
yarn workspaces run upgrade
279

280
# Remove dependency from specific workspace
281
yarn workspace @company/package-a remove old-dependency
282
```
283

284
### Development Workflow
285

286
```bash
287
# Install all workspace dependencies
288
yarn install
289

290
# Build all packages in dependency order
291
yarn workspaces run build
292

293
# Test all packages
294
yarn workspaces run test
295

296
# Lint all packages
297
yarn workspaces run lint
298

299
# Clean all build artifacts
300
yarn workspaces run clean
301

302
# Watch mode for development
303
yarn workspaces run dev
304
```
305

306
## Workspace Best Practices
307

308
### Project Structure
309

310
```
311
monorepo/
312
├── package.json              # Root config, shared dependencies
313
├── yarn.lock                 # Single lockfile for entire repo
314
├── .gitignore               # Shared git ignore
315
├── .eslintrc.js             # Shared linting config
316
├── jest.config.js           # Shared test config
317
├── tsconfig.json            # Base TypeScript config
318
├── packages/                # Library packages
319
│   ├── core/
320
│   ├── utils/
321
│   └── ui-components/
322
├── apps/                    # Application packages
323
│   ├── web-app/
324
│   ├── mobile-app/
325
│   └── admin-dashboard/
326
└── tools/                   # Build tools and scripts
327
    ├── build-scripts/
328
    └── dev-tools/
329
```
330

331
### Script Organization
332

333
**Root package.json:**
334
```json
335
{
336
  "scripts": {
337
    "build": "yarn workspaces run build",
338
    "build:libs": "yarn workspace @company/core build && yarn workspace @company/utils build",
339
    "test": "jest --projects packages/*/jest.config.js",
340
    "test:unit": "yarn workspaces run test:unit", 
341
    "test:integration": "yarn workspaces run test:integration",
342
    "lint": "eslint packages/*/src/**/*.{js,ts,tsx}",
343
    "lint:fix": "yarn lint --fix",
344
    "typecheck": "yarn workspaces run typecheck",
345
    "clean": "yarn workspaces run clean",
346
    "dev": "yarn workspaces run dev",
347
    "version": "yarn workspaces run version"
348
  }
349
}
350
```
351

352
### Dependency Strategy
353

354
```json
355
{
356
  "devDependencies": {
357
    // Shared development tools at root
358
    "typescript": "^4.8.0",
359
    "jest": "^29.0.0", 
360
    "eslint": "^8.0.0",
361
    "@types/node": "^18.0.0"
362
  },
363
  "workspaces": [
364
    "packages/*",
365
    "apps/*" 
366
  ]
367
}
368
```
369

370
### Cross-Package Dependencies
371

372
```bash
373
# Link workspace packages properly
374
yarn workspace @company/app add @company/core
375
yarn workspace @company/app add @company/utils
376

377
# This creates proper symlinks and version references
378
```
379

380
### Publishing Workspaces
381

382
```bash
383
# Publish all public packages
384
yarn workspaces foreach --no-private publish
385

386
# Version all packages together
387
yarn workspaces foreach version patch
388

389
# Publish with specific tag
390
yarn workspaces foreach --no-private publish --tag beta
391
```
392

393
## Common Workspace Patterns
394

395
### Shared Configuration
396

397
```javascript
398
// jest.config.js (root)
399
module.exports = {
400
  projects: ['<rootDir>/packages/*/jest.config.js'],
401
  collectCoverageFrom: [
402
    'packages/*/src/**/*.{js,ts}',
403
    '!packages/*/src/**/*.d.ts'
404
  ]
405
};
406

407
// tsconfig.json (root)
408
{
409
  "compilerOptions": {
410
    "baseUrl": ".",
411
    "paths": {
412
      "@company/*": ["packages/*/src"]
413
    }
414
  },
415
  "references": [
416
    { "path": "./packages/core" },
417
    { "path": "./packages/utils" },
418
    { "path": "./apps/web-app" }
419
  ]
420
}
421
```
422

423
### Development Scripts
424

425
```bash
426
# Development with watch mode
427
yarn workspace @company/core dev &
428
yarn workspace @company/web-app dev &
429
wait
430

431
# Testing across workspaces
432
yarn test --projects packages/core packages/utils
433

434
# Building in correct order
435
yarn workspace @company/core build
436
yarn workspace @company/utils build  
437
yarn workspace @company/web-app build
438
```