0
# Package Operations
1

2
Executing arbitrary commands across packages and managing package relationships.
3

4
## Capabilities
5

6
### Execute Commands
7

8
Run arbitrary commands across packages with flexible filtering and execution options.
9

10
```bash { .api }
11
# Execute command in all packages
12
lerna exec -- <command>
13

14
# Execute specific commands
15
lerna exec -- rm -rf node_modules
16
lerna exec -- npm audit fix
17
lerna exec -- git status
18
lerna exec -- ls -la
19

20
# Execute with package filtering
21
lerna exec --scope="@myorg/*" -- npm run build
22
lerna exec --ignore="*-test" -- npm install
23
lerna exec --since HEAD~1 -- npm test
24

25
# Execute in parallel
26
lerna exec --parallel -- npm run lint
27

28
# Execute with streaming output
29
lerna exec --stream -- npm run start
30

31
# Execute in specific directory
32
lerna exec --scope=package-name -- npm run dev
33

34
# Pass environment variables
35
lerna exec -- env NODE_ENV=production npm run build
36
```
37

38
### Exec Command Options
39

40
```bash { .api }
41
# Execution control
42
--parallel          # Execute in parallel across packages
43
--stream            # Stream output immediately
44
--concurrency <n>   # Limit concurrent processes
45
--bail              # Stop on first command failure (default)
46
--no-bail           # Continue despite command failures
47
--no-prefix         # Do not prefix streaming output
48
--profile           # Profile command executions and output performance data
49
--profile-location  # Output performance profile to custom location
50

51
# Package filtering
52
--scope <glob>      # Include packages matching glob
53
--ignore <glob>     # Exclude packages matching glob
54
--since <ref>       # Include packages changed since ref
55
--include-dependencies    # Include dependencies
56
--include-dependents     # Include dependents
57
--no-private        # Exclude private packages
58

59
# Output control
60
--silent            # Suppress command output
61
--loglevel <level>  # Control log verbosity
62
```
63

64
### Clean Operation
65

66
Remove node_modules directories from all packages.
67

68
```bash { .api }
69
# Remove node_modules from all packages
70
lerna clean
71

72
# Clean with confirmation
73
lerna clean --yes
74

75
# Clean specific packages
76
lerna clean --scope="@myorg/*"
77
lerna clean --ignore="core-*"
78

79
# Clean changed packages only
80
lerna clean --since HEAD~1
81
```
82

83
**Clean operation:**
84
- Removes `node_modules` directories from all packages
85
- Preserves root `node_modules` (workspace dependencies)
86
- Prompts for confirmation unless `--yes` is used
87
- Respects package filtering options
88

89
### Import Package
90

91
Import an external package repository into the monorepo with full commit history.
92

93
```bash { .api }
94
# Import external repository
95
lerna import <path-to-external-repository>
96

97
# Import with options
98
lerna import /path/to/external-repo --flatten
99
lerna import /path/to/external-repo --max-buffer=1048576
100

101
# Import examples
102
lerna import ../my-existing-package
103
lerna import ~/projects/standalone-library
104
```
105

106
**Import operation:**
107
- Imports entire git history from external repository
108
- Preserves original commit authors, dates, and messages
109
- Applies commits to current branch with package prefix
110
- Moves files to `packages/<directory-name>/` structure
111
- Requires clean working directory before import
112
- External repository remains unchanged
113

114
**Import options:**
115
- `--flatten` - Import history in "flat" mode (single level)
116
- `--max-buffer=<size>` - Increase buffer size for large repositories
117
- `--dest=<directory>` - Specify destination directory name
118

119
## Advanced Operations
120

121
### Environment-Specific Commands
122

123
```bash { .api }
124
# Development environment setup
125
lerna exec -- npm run setup:dev
126

127
# Production builds
128
lerna exec --parallel -- npm run build:prod
129

130
# Environment-specific installs
131
lerna exec -- npm install --production
132
```
133

134
### File System Operations
135

136
```bash { .api }
137
# Remove build artifacts
138
lerna exec -- rm -rf dist/ build/ lib/
139

140
# Copy configuration files
141
lerna exec -- cp ../shared/.eslintrc.js .
142

143
# Create directories
144
lerna exec -- mkdir -p dist/assets
145

146
# Archive packages
147
lerna exec -- tar -czf "../archive/${PWD##*/}.tar.gz" .
148
```
149

150
### Package Maintenance
151

152
```bash { .api }
153
# Update dependencies
154
lerna exec -- npm update
155

156
# Audit and fix vulnerabilities
157
lerna exec -- npm audit fix
158

159
# Clean and reinstall
160
lerna clean --yes && npm install
161

162
# Update package metadata
163
lerna exec -- npm pkg set engines.node=">=18"
164
```
165

166
### Git Operations
167

168
```bash { .api }
169
# Check git status across packages
170
lerna exec -- git status --porcelain
171

172
# Add git hooks
173
lerna exec -- cp ../shared/pre-commit .git/hooks/
174

175
# Reset git state
176
lerna exec -- git reset --hard HEAD
177

178
# Apply git patches
179
lerna exec -- git apply ../patches/${PWD##*/}.patch
180
```
181

182
## Command Context
183

184
### Available Variables
185

186
Commands executed via `lerna exec` have access to:
187

188
- `$LERNA_PACKAGE_NAME` - Current package name
189
- `$LERNA_ROOT_PATH` - Path to workspace root
190
- `$PWD` - Current package directory
191
- All standard environment variables
192

193
```bash { .api }
194
# Use package name in command
195
lerna exec -- echo "Building $LERNA_PACKAGE_NAME"
196

197
# Reference workspace root
198
lerna exec -- cp "$LERNA_ROOT_PATH/shared/config.js" ./
199

200
# Package-specific operations
201
lerna exec -- mkdir -p "$LERNA_ROOT_PATH/dist/$LERNA_PACKAGE_NAME"
202
```
203

204
### Working Directory
205

206
Commands execute in each package's root directory:
207

208
```bash { .api }
209
# Current directory is package root
210
lerna exec -- pwd
211
# /workspace/packages/package-a
212
# /workspace/packages/package-b
213

214
# Access package.json
215
lerna exec -- cat package.json
216

217
# Access source files
218
lerna exec -- ls src/
219
```
220

221
## Filtering and Selection
222

223
### Scope-Based Filtering
224

225
```bash { .api }
226
# Include packages by pattern
227
lerna exec --scope="@myorg/*" -- npm run build
228
lerna exec --scope="*-api" -- npm test
229
lerna exec --scope="frontend-*" -- npm run lint
230

231
# Exclude packages by pattern
232
lerna exec --ignore="*-test" -- npm run build  
233
lerna exec --ignore="@internal/*" -- npm publish
234

235
# Multiple patterns
236
lerna exec --scope="@myorg/*" --ignore="*-test" -- npm run validate
237
```
238

239
### Change-Based Filtering
240

241
```bash { .api }
242
# Execute only in changed packages
243
lerna exec --since HEAD~1 -- npm run build
244

245
# Include dependencies of changed packages
246
lerna exec --since v1.0.0 --include-dependencies -- npm test
247

248
# Include dependents of changed packages
249
lerna exec --since origin/main --include-dependents -- npm run build
250
```
251

252
### Property-Based Filtering
253

254
```bash { .api }
255
# Execute only in public packages
256
lerna exec --no-private -- npm publish
257

258
# Execute only in private packages
259
lerna exec --private -- npm run internal-check
260
```
261

262
## Performance and Parallelization
263

264
### Parallel Execution
265

266
```bash { .api }
267
# Maximum parallelism
268
lerna exec --parallel -- npm run lint
269

270
# Controlled concurrency
271
lerna exec --concurrency 4 -- npm test
272

273
# Stream output for monitoring
274
lerna exec --parallel --stream -- npm run dev
275
```
276

277
**Use parallel execution for:**
278
- Independent operations (lint, test, format)
279
- Long-running processes (dev servers)
280
- Operations that don't depend on other packages
281

282
**Use sequential execution for:**
283
- Build operations with dependencies
284
- Operations that modify shared resources
285
- Commands that require specific ordering
286

287
### Error Handling
288

289
```bash { .api }
290
# Stop on first failure (default)
291
lerna exec --bail -- npm run build
292

293
# Continue despite failures
294
lerna exec --no-bail -- npm test
295

296
# Combine with logging for analysis
297
lerna exec --no-bail --loglevel=error -- npm audit
298
```
299

300
## Integration Patterns
301

302
### CI/CD Pipeline Integration
303

304
```bash { .api }
305
# Pre-deployment checks
306
lerna exec --parallel -- npm run lint
307
lerna exec --since HEAD~1 -- npm test
308
lerna exec --no-private -- npm run build
309

310
# Post-deployment cleanup
311
lerna exec -- npm prune --production
312
```
313

314
### Development Workflow
315

316
```bash { .api }
317
# Setup new development environment
318
lerna clean --yes
319
npm install
320
lerna exec -- npm run setup
321

322
# Daily development routine
323
lerna exec --since HEAD~1 --include-dependents -- npm run build
324
lerna exec --parallel -- npm run test:watch
325
```
326

327
### Maintenance Tasks
328

329
```bash { .api }
330
# Security updates
331
lerna exec -- npm audit fix --force
332

333
# Dependency updates
334
lerna exec -- npm update
335
lerna exec -- npm outdated
336

337
# Code formatting
338
lerna exec --parallel -- npm run format
339
lerna exec --parallel -- npm run lint:fix
340
```