0
# Lerna Init
1
2
Lerna Init creates new Lerna repositories or upgrades existing repositories to the current version of Lerna. It handles the initialization of monorepo project structures by creating essential configuration files, setting up directory structures, and configuring workspace dependencies.
3
4
## Package Information
5
6
- **Package Name**: @lerna/init
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @lerna/init`
10
- **Node Version**: ^14.17.0 || >=16.0.0
11
12
## Core Imports
13
14
```typescript
15
import initFactory from "@lerna/init";
16
import { InitCommand } from "@lerna/init";
17
import command from "@lerna/init/command";
18
```
19
20
CommonJS:
21
22
```javascript
23
const initFactory = require("@lerna/init");
24
const { InitCommand } = require("@lerna/init");
25
const command = require("@lerna/init/command");
26
```
27
28
## Basic Usage
29
30
```typescript
31
import initFactory from "@lerna/init";
32
33
// Create InitCommand instance using factory
34
const initCommand = initFactory(process.argv);
35
36
// Execute initialization
37
await initCommand.execute();
38
```
39
40
Using InitCommand directly:
41
42
```typescript
43
import { InitCommand } from "@lerna/init";
44
45
// Create command instance
46
const initCommand = new InitCommand(process.argv);
47
await initCommand.execute();
48
```
49
50
Using as command module:
51
52
```typescript
53
import command from "@lerna/init/command";
54
55
// Command configuration for CLI
56
const initModule = {
57
command: "init",
58
describe: "Create a new Lerna repo or upgrade an existing repo to the current version of Lerna",
59
builder: command.builder,
60
handler: command.handler
61
};
62
```
63
64
## Architecture
65
66
Lerna Init is built around several key components:
67
68
- **Factory Function**: Main export creates InitCommand instances with provided arguments
69
- **InitCommand Class**: Core command class extending Lerna's base Command class
70
- **Configuration Management**: Handles lerna.json and package.json creation/updates
71
- **File System Operations**: Creates directory structures and essential files
72
- **Git Integration**: Optionally initializes Git repositories when needed
73
74
## Capabilities
75
76
### Command Factory
77
78
Creates new InitCommand instances for repository initialization.
79
80
```typescript { .api }
81
/**
82
* Factory function that creates new InitCommand instances
83
* @param argv - Command line arguments from Node.js process
84
* @returns InitCommand instance ready for execution
85
*/
86
function factory(argv: NodeJS.Process["argv"]): InitCommand;
87
```
88
89
### InitCommand Class
90
91
Main command class that handles Lerna repository initialization logic.
92
93
```typescript { .api }
94
/**
95
* Command class for initializing Lerna repositories
96
* Extends the base Command class from @lerna/core
97
*/
98
class InitCommand extends Command<InitCommandOptions> {
99
/** Whether to use exact version matching for dependencies */
100
exact?: boolean;
101
102
/** Version of Lerna to install in the repository */
103
lernaVersion: string;
104
105
/** Whether Git repository is required (always false for init) */
106
get requiresGit(): boolean;
107
108
/**
109
* Initialize the command, optionally creating Git repository
110
* @returns Promise that resolves when initialization is complete
111
*/
112
override initialize(): Promise<void>;
113
114
/**
115
* Execute the initialization process
116
* @returns Promise that resolves when all initialization steps complete
117
*/
118
override execute(): Promise<void>;
119
120
/**
121
* Skip validation phase (overridden for init command)
122
*/
123
runValidations(): void;
124
125
/**
126
* Skip preparation phase (overridden for init command)
127
*/
128
runPreparations(): void;
129
130
/**
131
* Ensure .gitignore file exists with node_modules exclusion
132
* @returns Promise that resolves when .gitignore is created or exists
133
*/
134
ensureGitIgnore(): Promise<void>;
135
136
/**
137
* Create or update lerna.json and package.json configuration files
138
* @returns Promise that resolves when configuration is complete
139
*/
140
ensureConfig(): Promise<void | Package>;
141
142
/**
143
* Create packages directory structure for monorepo
144
* @returns Promise that resolves when directories are created
145
*/
146
ensurePackagesDir(): Promise<void[]>;
147
}
148
```
149
150
### Command Module Configuration
151
152
Yargs command module configuration for CLI integration.
153
154
```typescript { .api }
155
/**
156
* Yargs command module for the init command
157
*/
158
interface CommandModule {
159
/** Command name used in CLI */
160
command: "init";
161
162
/** Command description for help text */
163
describe: "Create a new Lerna repo or upgrade an existing repo to the current version of Lerna";
164
165
/** Command options builder configuration */
166
builder: {
167
exact: {
168
describe: "Specify lerna dependency version in package.json without a caret (^)";
169
type: "boolean";
170
};
171
independent: {
172
describe: "Version packages independently";
173
alias: "i";
174
type: "boolean";
175
};
176
};
177
178
/**
179
* Command handler that executes the init command
180
* @param argv - Parsed command line arguments
181
* @returns InitCommand instance created by factory
182
*/
183
handler(argv: any): InitCommand;
184
}
185
```
186
187
### Core Dependencies
188
189
Types and interfaces from the Lerna core system.
190
191
```typescript { .api }
192
/**
193
* Base command class from @lerna/core that InitCommand extends
194
*/
195
abstract class Command<T extends CommandConfigOptions> {
196
constructor(argv: NodeJS.Process["argv"]);
197
abstract initialize(): Promise<void>;
198
abstract execute(): Promise<void>;
199
}
200
201
/**
202
* Package representation from @lerna/core
203
*/
204
interface Package {
205
name: string;
206
version: string;
207
location: string;
208
dependencies?: Record<string, string>;
209
devDependencies?: Record<string, string>;
210
serialize(): Promise<void>;
211
}
212
213
/**
214
* Base command configuration options from @lerna/core
215
*/
216
interface CommandConfigOptions {
217
_?: string[];
218
concurrency?: number;
219
sort?: boolean;
220
maxBuffer?: number;
221
stream?: boolean;
222
loglevel?: string;
223
verbose?: boolean;
224
progress?: boolean;
225
npmClient?: string;
226
}
227
228
/**
229
* Options interface for InitCommand configuration
230
*/
231
interface InitCommandOptions extends CommandConfigOptions {
232
/** Use exact version matching for lerna dependency (no caret prefix) */
233
exact: boolean;
234
235
/** Version of Lerna to install as dependency */
236
lernaVersion: string;
237
}
238
```
239
240
## Command Line Usage
241
242
The init command supports the following options:
243
244
### --exact
245
246
Specify lerna dependency version in package.json without a caret (^) prefix.
247
248
```bash
249
lerna init --exact
250
```
251
252
This creates exact version matching and saves the setting in lerna.json:
253
254
```json
255
{
256
"command": {
257
"init": {
258
"exact": true
259
}
260
}
261
}
262
```
263
264
### --independent / -i
265
266
Version packages independently rather than using fixed versioning.
267
268
```bash
269
lerna init --independent
270
# or
271
lerna init -i
272
```
273
274
This sets the version field in lerna.json to "independent".
275
276
## Files Created/Modified
277
278
### lerna.json
279
280
Main Lerna configuration file created with:
281
- JSON schema reference
282
- Version number (0.0.0 or "independent")
283
- Workspace configuration
284
- Package glob patterns
285
- Nx integration settings
286
287
### package.json
288
289
Root package.json created/updated with:
290
- Private flag set to true
291
- Workspaces configuration
292
- Lerna devDependency
293
- Root package name
294
295
### .gitignore
296
297
Git ignore file created with node_modules exclusion if not present.
298
299
### packages/
300
301
Directory structure created for monorepo packages.
302
303
## Integration Notes
304
305
- **Git Integration**: Optionally initializes Git repository if not present
306
- **Workspace Support**: Configures npm workspaces by default
307
- **Nx Integration**: Enables Nx integration unless explicitly disabled
308
- **Schema Validation**: Includes JSON schema reference for IDE support
309
- **Dependency Management**: Handles both dependencies and devDependencies placement