0
# Configuration
1

2
Interactive configuration and optimization tools for monorepo setup.
3

4
## Capabilities
5

6
### Initialize Workspace
7

8
Create a new Lerna workspace with proper configuration.
9

10
```bash { .api }
11
# Initialize new Lerna workspace
12
lerna init
13

14
# Initialize with independent versioning
15
lerna init --independent
16

17
# Initialize with Nx integration
18
lerna init --use-nx
19

20
# Initialize in existing workspace
21
lerna init --exact
22

23
# Additional initialization options
24
lerna init --packages "packages/*,libs/*"  # Custom package patterns
25
lerna init --dry-run                       # Preview changes without modifying
26
lerna init --skip-install                  # Skip dependency installation
27
```
28

29
**Initialization creates:**
30
- `lerna.json` configuration file
31
- `package.json` with workspace configuration
32
- Initial package structure
33
- Git repository (if none exists)
34

35
### Create New Package
36

37
Create a new lerna-managed package within the workspace.
38

39
```bash { .api }
40
# Create new package with basic setup
41
lerna create <name>
42

43
# Create package in specific location
44
lerna create <name> [location]
45

46
# Create with additional options
47
lerna create my-package --description "My package description"
48
lerna create @myorg/ui-components --private
49
lerna create my-cli --bin --es-module
50
```
51

52
**Package Creation Options:**
53

54
- `--access` - When using a scope, set publishConfig.access value (public, restricted)
55
- `--bin` - Package has an executable. Optionally specify executable name
56
- `--description` - Package description
57
- `--dependencies` - Array of package dependencies to add
58
- `--es-module` - Initialize as a transpiled ES Module
59
- `--homepage` - Package homepage URL
60
- `--keywords` - Array of package keywords
61
- `--license` - SPDX license identifier (default: ISC)
62
- `--private` - Make package private, never published externally
63
- `--registry` - Configure the package's publishConfig.registry
64
- `--tag` - Configure the package's publishConfig.tag
65
- `--yes` / `-y` - Skip all prompts, accepting default values
66

67
**Package Creation Process:**
68
1. **Location Selection**: Uses first configured package location or specified location
69
2. **Package Structure**: Creates standard package directory structure
70
3. **Package.json Generation**: Generates package.json with specified options
71
4. **Template Setup**: Applies appropriate package template (standard or ES module)
72
5. **Dependency Management**: Adds specified dependencies to package.json
73
6. **Git Integration**: Stages new package files for commit
74

75
**Usage Examples:**
76

77
```bash
78
# Create basic package
79
lerna create utils
80

81
# Create scoped private package  
82
lerna create @myorg/internal-utils --private --description "Internal utilities"
83

84
# Create CLI package with executable
85
lerna create my-cli --bin my-cli --keywords cli,tools
86

87
# Create ES module package with dependencies
88
lerna create modern-utils --es-module --dependencies lodash,axios
89

90
# Create package in custom location
91
lerna create special-package ./libs
92

93
# Create package non-interactively
94
lerna create batch-package --yes --license MIT --homepage "https://myorg.com"
95
```
96

97
### Add Caching Configuration
98

99
Interactive configuration generator for Nx task runner caching.
100

101
```bash { .api }
102
# Configure caching interactively
103
lerna add-caching
104

105
# Available when useNx is enabled in lerna.json
106
```
107

108
**Add Caching Process:**
109
1. **Script Discovery**: Finds all npm scripts across packages
110
2. **Dependency Configuration**: Configure which scripts need to run in order
111
3. **Caching Configuration**: Select which scripts produce cacheable outputs
112
4. **Output Configuration**: Specify output directories for cached scripts
113
5. **Nx Configuration**: Updates `nx.json` with optimized settings
114
6. **Git Integration**: Adds `.nx/cache` to `.gitignore`
115

116
### Repair Workspace
117

118
Automated migrations to repair workspace state and apply updates.
119

120
```bash { .api }
121
# Run automated repairs
122
lerna repair
123

124
# Run with verbose output for debugging
125
lerna repair --verbose
126
```
127

128
**Repair operations:**
129
- Fix broken workspace configurations
130
- Update deprecated settings
131
- Migrate legacy configurations
132
- Resolve package inconsistencies
133
- Apply security patches to workspace setup
134

135
### Watch Mode
136

137
Watch for changes in packages and automatically execute commands when changes occur.
138

139
```bash { .api }
140
# Watch for changes and run command
141
lerna watch -- <command>
142

143
# Examples
144
lerna watch -- npm run build
145
lerna watch -- npm test
146
lerna watch -- echo "Files changed in $LERNA_PACKAGE_NAME"
147

148
# Watch with verbose output
149
lerna watch --verbose -- npm run build
150

151
# Watch specific packages
152
lerna watch --scope="@myorg/*" -- npm run build
153
lerna watch --ignore="*-test" -- npm run lint
154
```
155

156
**Watch command features:**
157
- Monitors file changes in workspace packages
158
- Executes specified command when changes are detected
159
- Respects package filtering options (scope, ignore, since)
160
- Provides environment variables `$LERNA_PACKAGE_NAME` and `$LERNA_FILE_CHANGES`
161
- Uses Nx watch capabilities for efficient change detection
162

163
### Environment Information
164

165
Display environment and configuration information for debugging.
166

167
```bash { .api }
168
# Show environment information
169
lerna info
170

171
# Display Lerna version, Node.js version, npm version
172
# Show workspace configuration
173
# List detected packages
174
```
175

176
## Configuration Files
177

178
### lerna.json Configuration
179

180
Primary Lerna configuration file:
181

182
```json { .api }
183
{
184
  "version": "1.0.0",
185
  "packages": ["packages/*"],
186
  "useNx": true,
187
  "npmClient": "npm",
188
  "registry": "https://registry.npmjs.org",
189
  "command": {
190
    "publish": {
191
      "conventionalCommits": true,
192
      "message": "chore: publish",
193
      "registry": "https://registry.npmjs.org",
194
      "access": "public"
195
    },
196
    "version": {
197
      "allowBranch": ["main", "master"],
198
      "conventionalCommits": true,
199
      "createRelease": "github",
200
      "push": true
201
    },
202
    "bootstrap": {
203
      "npmClientArgs": ["--no-package-lock"]
204
    }
205
  },
206
  "ignoreChanges": [
207
    "**/*.md",
208
    "**/test/**",
209
    "**/__tests__/**"
210
  ]
211
}
212
```
213

214
### Configuration Schema
215

216
```typescript { .api }
217
interface LernaConfig {
218
  /** Workspace version (fixed) or "independent" */
219
  version: string;
220
  
221
  /** Package location patterns */
222
  packages: string[];
223
  
224
  /** Use Nx task runner for enhanced performance */
225
  useNx?: boolean;
226
  
227
  /** npm client (npm, yarn, pnpm) */
228
  npmClient?: 'npm' | 'yarn' | 'pnpm';
229
  
230
  /** Default npm registry */
231
  registry?: string;
232
  
233
  /** Command-specific configurations */
234
  command?: {
235
    publish?: PublishConfig;
236
    version?: VersionConfig;
237
    bootstrap?: BootstrapConfig;
238
    run?: RunConfig;
239
    exec?: ExecConfig;
240
  };
241
  
242
  /** Patterns to ignore for change detection */
243
  ignoreChanges?: string[];
244
  
245
  /** Nx-specific configuration */
246
  useWorkspaces?: boolean;
247
  granularPathspec?: boolean;
248
}
249

250
interface PublishConfig {
251
  conventionalCommits?: boolean;
252
  message?: string;
253
  registry?: string;
254
  access?: 'public' | 'restricted';
255
  distTag?: string;
256
  skipNpm?: boolean;
257
  skipGit?: boolean;
258
  yes?: boolean;
259
  verifyAccess?: boolean;
260
}
261

262
interface VersionConfig {
263
  allowBranch?: string | string[];
264
  conventionalCommits?: boolean;
265
  createRelease?: 'github' | 'gitlab';
266
  push?: boolean;
267
  exact?: boolean;
268
  message?: string;
269
  signGitCommit?: boolean;
270
  signGitTag?: boolean;
271
}
272

273
interface BootstrapConfig {
274
  npmClientArgs?: string[];
275
  hoist?: boolean | string[];
276
  nohoist?: string[];
277
  ignore?: string[];
278
  ignorePrepublish?: boolean;
279
}
280

281
interface RunConfig {
282
  npmClient?: string;
283
  stream?: boolean;
284
  parallel?: boolean;
285
  bail?: boolean;
286
}
287

288
interface ExecConfig {
289
  bail?: boolean;
290
  parallel?: boolean;
291
  stream?: boolean;
292
}
293
```
294

295
### Package.json Workspace Configuration
296

297
Configure workspace in root package.json:
298

299
```json { .api }
300
{
301
  "name": "my-workspace",
302
  "private": true,
303
  "workspaces": [
304
    "packages/*"
305
  ],
306
  "devDependencies": {
307
    "lerna": "^8.2.4"
308
  },
309
  "scripts": {
310
    "build": "lerna run build",
311
    "test": "lerna run test", 
312
    "publish": "lerna publish",
313
    "version": "lerna version"
314
  }
315
}
316
```
317

318
### Nx Configuration
319

320
When `useNx: true`, configure task runner via nx.json:
321

322
```json { .api }
323
{
324
  "targetDefaults": {
325
    "build": {
326
      "dependsOn": ["^build"],
327
      "cache": true,
328
      "outputs": ["{projectRoot}/dist", "{projectRoot}/lib"]
329
    },
330
    "test": {
331
      "cache": true,
332
      "outputs": ["{projectRoot}/coverage"]
333
    },
334
    "lint": {
335
      "cache": true
336
    }
337
  },
338
  "cacheDirectory": ".nx/cache",
339
  "defaultBase": "main"
340
}
341
```
342

343
## Environment Configuration
344

345
### npm Configuration
346

347
Configure npm behavior via `.npmrc`:
348

349
```ini
350
# Registry configuration
351
registry=https://registry.npmjs.org
352
@myorg:registry=https://custom-registry.com
353

354
# Authentication
355
//registry.npmjs.org/:_authToken=${NPM_TOKEN}
356
//custom-registry.com/:_authToken=${CUSTOM_TOKEN}
357

358
# Package configuration
359
save-exact=true
360
package-lock=false
361
```
362

363
### Git Configuration  
364

365
Configure git behavior:
366

367
```bash { .api }
368
# Set commit message template
369
git config commit.template .gitmessage
370

371
# Configure signing
372
git config commit.gpgsign true
373
git config tag.gpgsign true
374

375
# Set default branch
376
git config init.defaultBranch main
377
```
378

379
## Workspace Structure
380

381
### Standard Layout
382

383
```
384
workspace/
385
├── lerna.json
386
├── package.json
387
├── nx.json (if useNx: true)
388
├── packages/
389
│   ├── package-a/
390
│   │   ├── package.json
391
│   │   └── src/
392
│   └── package-b/
393
│       ├── package.json
394
│       └── src/
395
├── tools/ (optional)
396
├── docs/ (optional)
397
└── .github/ (CI/CD)
398
```
399

400
### Package Structure
401

402
Standard package layout:
403

404
```
405
packages/my-package/
406
├── package.json
407
├── src/
408
├── lib/ or dist/ (build output)
409
├── test/ or __tests__/
410
├── README.md
411
└── CHANGELOG.md (generated)
412
```
413

414
## Migration and Upgrades
415

416
### Legacy Configuration Migration
417

418
```bash { .api }
419
# Migrate from legacy Lerna configuration
420
lerna repair
421

422
# Update deprecated options
423
lerna repair --verbose
424
```
425

426
### Nx Migration
427

428
Enable Nx for existing workspace:
429

430
```json
431
{
432
  "useNx": true
433
}
434
```
435

436
Then run:
437

438
```bash { .api }
439
# Configure Nx caching
440
lerna add-caching
441

442
# Initialize nx.json if needed
443
npx nx init
444
```
445

446
## Troubleshooting
447

448
### Common Configuration Issues
449

450
```bash { .api }
451
# Verify configuration
452
lerna info
453

454
# Check package detection
455
lerna list --all
456

457
# Validate workspace structure
458
lerna exec -- pwd
459

460
# Debug configuration loading
461
lerna --loglevel=verbose list
462
```
463

464
### Configuration Validation
465

466
```bash { .api }
467
# Validate lerna.json syntax
468
node -e "console.log(JSON.parse(require('fs').readFileSync('lerna.json')))"
469

470
# Check workspace packages match configuration
471
lerna list --json | jq '.[].location'
472

473
# Verify nx.json syntax (if using Nx)
474
npx nx show projects
475
```
476

477
### Reset Configuration
478

479
```bash { .api }
480
# Reset to default configuration
481
rm lerna.json nx.json
482
lerna init
483

484
# Clean workspace state
485
lerna clean --yes
486
npm install
487

488
# Repair any issues
489
lerna repair
490
```