0
# Script Execution
1

2
Running npm scripts across packages with dependency-aware execution and caching.
3

4
## Capabilities
5

6
### Run Scripts
7

8
Execute npm scripts across multiple packages with intelligent dependency handling.
9

10
```bash { .api }
11
# Run script in all packages that have it
12
lerna run <script>
13

14
# Run specific script examples
15
lerna run test
16
lerna run build  
17
lerna run lint
18
lerna run start
19

20
# Run script in specific packages
21
lerna run test --scope=package-name
22
lerna run build --scope="@myorg/*"
23

24
# Run script in changed packages only
25
lerna run test --since HEAD~1
26
lerna run build --since v1.0.0
27

28
# Run script with parallel execution
29
lerna run test --parallel
30

31
# Run script with streaming output
32
lerna run test --stream
33

34
# Run script in topological order (dependencies first)
35
lerna run build --sort
36

37
# Ignore script failures and continue
38
lerna run test --no-bail
39

40
# Include dependencies/dependents
41
lerna run build --include-dependencies
42
lerna run test --include-dependents
43

44
# Pass arguments to scripts
45
lerna run test -- --coverage
46
lerna run build -- --minify --sourcemap
47

48
# Run multiple scripts concurrently (comma-separated)
49
lerna run "lint,test,build"
50
lerna run "test,lint" --parallel
51
```
52

53
### Script Execution Options
54

55
```bash { .api }
56
# Execution control
57
--parallel          # Run scripts in parallel (ignores concurrency)
58
--stream            # Stream output immediately (implies --parallel)
59
--no-sort           # Don't run in topological order
60
--concurrency <n>   # Maximum number of concurrent processes
61
--bail              # Stop on first script failure (default)
62
--no-bail           # Continue despite script failures
63

64
# Output control  
65
--silent            # Suppress script output
66
--loglevel <level>  # Set log level (silent, error, warn, notice, http, timing, info, verbose, silly)
67
--no-prefix         # Do not prefix streaming output
68
--npm-client <cmd>  # Executable used to run scripts (npm, yarn, pnpm, etc.)
69

70
# Package filtering
71
--scope <glob>      # Include packages matching glob
72
--ignore <glob>     # Exclude packages matching glob  
73
--since <ref>       # Include packages changed since ref
74
--include-dependencies    # Include dependencies of matched packages
75
--include-dependents     # Include dependents of matched packages
76
--include-merged-tags    # Include packages from merged tags
77

78
# Nx integration (when useNx: true)
79
--skip-nx-cache     # Skip Nx caching
80
--nx-bail           # Stop on first Nx task failure
81
--nx-ignore-cycles  # Ignore dependency cycles in Nx
82
```
83

84
### Parallel Execution
85

86
```bash { .api }
87
# Run scripts in parallel
88
lerna run build --parallel
89

90
# Control concurrency
91
lerna run test --concurrency 4
92

93
# Stream output for better feedback
94
lerna run start --stream
95
```
96

97
**Parallel execution:**
98
- Ignores package dependency order
99
- Runs all matching packages simultaneously
100
- Best for independent operations (test, lint)
101
- Use `--stream` for real-time output
102

103
**Sequential execution (default):**
104
- Respects package dependency order
105
- Runs packages topologically
106
- Best for build operations where dependencies matter
107

108
### Nx Integration
109

110
When `useNx: true` in lerna.json, script execution uses Nx task runner:
111

112
```bash { .api }
113
# Nx-powered script execution with caching
114
lerna run build
115

116
# Skip Nx cache
117
lerna run build --skip-nx-cache
118

119
# Nx task configuration via nx.json
120
lerna run build --with-deps  # Uses Nx dependency detection
121
```
122

123
**Nx benefits:**
124
- Intelligent caching based on file changes
125
- Distributed task execution
126
- Better performance for large workspaces
127
- Advanced dependency detection
128

129
## Script Configuration
130

131
### Package Scripts
132

133
Define scripts in package.json:
134

135
```json
136
{
137
  "scripts": {
138
    "build": "tsc",
139
    "test": "jest",
140
    "lint": "eslint src/",
141
    "start": "node dist/index.js",
142
    "clean": "rimraf dist/"
143
  }
144
}
145
```
146

147
### Workspace Scripts
148

149
Run scripts across the workspace:
150

151
```bash
152
# Run build in all packages that have it
153
lerna run build
154

155
# Packages without the script are skipped automatically
156
lerna run nonexistent-script  # Runs successfully, skips packages
157
```
158

159
### Script Dependencies
160

161
For dependent builds, use topological ordering:
162

163
```bash { .api }
164
# Build dependencies first, then dependents
165
lerna run build --sort
166

167
# Equivalent: (default behavior unless --parallel)
168
lerna run build
169
```
170

171
## Advanced Usage
172

173
### Conditional Execution
174

175
```bash { .api }
176
# Run only in packages with changes
177
lerna run build --since origin/main
178

179
# Run in packages with specific dependency
180
lerna run integration-test --scope="*api*"
181

182
# Run excluding test packages  
183
lerna run build --ignore="*-test" --ignore="test-*"
184
```
185

186
### Script Arguments
187

188
Pass arguments to underlying scripts:
189

190
```bash { .api }
191
# Pass coverage flag to test script
192
lerna run test -- --coverage --reporter=lcov
193

194
# Pass multiple arguments
195
lerna run build -- --minify --sourcemap --verbose
196

197
# Environment-specific builds
198
lerna run build -- --env=production --optimize
199
```
200

201
### Error Handling
202

203
```bash { .api }
204
# Stop on first failure (default)
205
lerna run test --bail
206

207
# Continue despite failures
208
lerna run test --no-bail
209

210
# Combine with reporting
211
lerna run test --no-bail --stream > test-results.log
212
```
213

214
### Output Management
215

216
```bash { .api }
217
# Suppress script output
218
lerna run build --silent
219

220
# Stream output for long-running processes
221
lerna run start --stream
222

223
# Control log levels
224
lerna run build --loglevel=error  # Only show errors
225
lerna run test --loglevel=verbose # Show detailed output
226
```
227

228
## Performance Optimization
229

230
### Caching with Nx
231

232
Configure nx.json for optimal caching:
233

234
```json
235
{
236
  "targetDefaults": {
237
    "build": {
238
      "dependsOn": ["^build"],
239
      "cache": true,
240
      "outputs": ["{projectRoot}/dist"]
241
    },
242
    "test": {
243
      "cache": true,
244
      "outputs": ["{projectRoot}/coverage"]
245
    }
246
  }
247
}
248
```
249

250
### Concurrency Control
251

252
```bash { .api }
253
# Optimize for CPU cores
254
lerna run build --concurrency $(nproc)
255

256
# Conservative concurrency for memory-intensive tasks
257
lerna run test --concurrency 2
258

259
# Maximum parallelism for independent tasks
260
lerna run lint --parallel
261
```
262

263
### Selective Execution
264

265
```bash { .api }
266
# Only build changed packages and their dependents
267
lerna run build --since HEAD~1 --include-dependents
268

269
# Test only packages with changes
270
lerna run test --since origin/main
271

272
# Build only public packages  
273
lerna run build --no-private
274
```