0
# Lerna
1

2
Lerna is a fast, modern build system for managing and publishing multiple JavaScript/TypeScript packages from the same repository. It provides tools for workspace management, dependency linking, selective building and testing of changed packages, automated versioning with conventional commits, coordinated publishing to npm registry, and distributed task execution with Nx integration.
3

4
## Package Information
5

6
- **Package Name**: lerna
7
- **Package Type**: npm
8
- **Language**: TypeScript/JavaScript
9
- **Installation**: `npm install lerna`
10
- **CLI Binary**: `lerna`
11

12
## Core Imports
13

14
```typescript
15
import { detectProjects } from "lerna/utils";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { detectProjects } = require("lerna/utils");
22
```
23

24
## Basic Usage
25

26
```bash
27
# Initialize a new Lerna workspace
28
lerna init
29

30
# Bootstrap workspace and install dependencies
31
npm install
32

33
# List all packages in the workspace
34
lerna list
35

36
# Run npm scripts across all packages
37
lerna run build
38

39
# Publish changed packages to npm
40
lerna publish
41

42
# Show which packages have changed
43
lerna changed
44
```
45

46
## Architecture
47

48
Lerna is built around several key components:
49

50
- **CLI Interface**: Primary interaction point providing all commands via `lerna <command>`
51
- **Command System**: Modular commands for different aspects of monorepo management
52
- **Package Discovery**: Automatic detection and management of packages within the workspace
53
- **Nx Integration**: Optional integration with Nx for enhanced caching and task orchestration
54
- **Git Integration**: Deep integration with git for change detection and version management
55
- **npm Integration**: Publishing, versioning, and dependency management with npm registry
56

57
## Capabilities
58

59
### Package Management
60

61
Core package discovery and workspace management functionality for identifying and working with packages in a monorepo.
62

63
```typescript { .api }
64
function detectProjects(rootDir?: string): Promise<{
65
  projectGraph: ProjectGraphWithPackages;
66
  projectFileMap: ProjectFileMap;
67
}>;
68
```
69

70
[Package Management](./package-management.md)
71

72
### Version Management
73

74
Automated versioning of packages with conventional commits, git tagging, and changelog generation.
75

76
```bash { .api }
77
lerna version [version]
78
lerna version --conventional-commits
79
lerna version --create-release github
80
```
81

82
[Version Management](./version-management.md)
83

84
### Publishing
85

86
Publishing packages to npm registry with coordinated releases and access verification.
87

88
```bash { .api }
89
lerna publish
90
lerna publish from-git
91
lerna publish from-package
92
```
93

94
[Publishing](./publishing.md)
95

96
### Script Execution
97

98
Running npm scripts across packages with dependency-aware execution and caching.
99

100
```bash { .api }
101
lerna run <script>
102
lerna run <script> --scope=<package>
103
lerna run <script> --since=<ref>
104
```
105

106
[Script Execution](./script-execution.md)
107

108
### Change Detection
109

110
Detecting which packages have changed since a given reference for selective operations.
111

112
```bash { .api }
113
lerna changed
114
lerna changed --since=<ref>
115
lerna diff [package]
116
lerna diff --since=<ref>
117
```
118

119
[Change Detection](./change-detection.md)
120

121
### Package Operations
122

123
Executing arbitrary commands across packages and managing package relationships.
124

125
```bash { .api }
126
lerna exec <command>
127
lerna exec <command> --scope=<package>
128
lerna clean
129
lerna import <path-to-external-repository>
130
```
131

132
[Package Operations](./package-operations.md)
133

134
### Workspace Configuration
135

136
Interactive configuration and optimization tools for monorepo setup and package creation.
137

138
```bash { .api }
139
lerna init
140
lerna create <name> [location]
141
lerna add-caching
142
lerna repair
143
lerna watch -- <command>
144
lerna info
145
```
146

147
[Configuration](./configuration.md)
148

149
## Core Types
150

151
```typescript { .api }
152
interface Package {
153
  name: string;
154
  version: string;
155
  location: string;
156
  private?: boolean;
157
  scripts?: Record<string, string>;
158
  dependencies?: Record<string, string>;
159
  devDependencies?: Record<string, string>;
160
  peerDependencies?: Record<string, string>;
161
  optionalDependencies?: Record<string, string>;
162
  bundleDependencies?: string[];
163
  bin?: string | Record<string, string>;
164
  binLocation?: string;
165
  manifestLocation: string;
166
  nodeModulesLocation: string;
167
  contents: string;
168
  
169
  /** Convert package to JSON representation */
170
  toJSON(): PackageJson;
171
  
172
  /** Get package manifest property */
173
  get(key: string): any;
174
  
175
  /** Set package manifest property */
176
  set(key: string, value: any): void;
177
}
178

179
interface LernaConfig {
180
  version?: string;
181
  packages?: string[];
182
  useNx?: boolean;
183
  npmClient?: string;
184
  registry?: string;
185
  command?: {
186
    publish?: PublishConfig;
187
    version?: VersionConfig;
188
    bootstrap?: BootstrapConfig;
189
  };
190
}
191

192
interface PublishConfig {
193
  registry?: string;
194
  access?: 'public' | 'restricted';
195
  message?: string;
196
  conventionalCommits?: boolean;
197
  yes?: boolean;
198
  distTag?: string;
199
}
200

201
interface VersionConfig {
202
  allowBranch?: string | string[];
203
  conventionalCommits?: boolean;
204
  message?: string;
205
  push?: boolean;
206
  createRelease?: 'github' | 'gitlab';
207
}
208

209
interface BootstrapConfig {
210
  npmClientArgs?: string[];
211
  hoist?: boolean | string[];
212
  nohoist?: string[];
213
  ignore?: string[];
214
}
215

216
interface ProjectGraphWithPackages {
217
  nodes: Record<string, ProjectGraphProjectNodeWithPackage>;
218
  dependencies: Record<string, ProjectGraphDependency[]>;
219
  localPackageDependencies: Record<string, ProjectGraphWorkspacePackageDependency[]>;
220
}
221

222
interface ProjectFileMap {
223
  [projectName: string]: ProjectFileMapProjectFiles;
224
}
225

226
interface ProjectGraphProjectNodeWithPackage {
227
  name: string;
228
  type: string;
229
  data: {
230
    root: string;
231
    sourceRoot?: string;
232
  };
233
  package: Package | null;
234
}
235

236
interface PackageJson {
237
  name: string;
238
  version: string;
239
  description?: string;
240
  main?: string;
241
  bin?: string | Record<string, string>;
242
  scripts?: Record<string, string>;
243
  dependencies?: Record<string, string>;
244
  devDependencies?: Record<string, string>;
245
  peerDependencies?: Record<string, string>;
246
  optionalDependencies?: Record<string, string>;
247
  bundleDependencies?: string[];
248
  private?: boolean;
249
  workspaces?: string[] | { packages: string[]; nohoist?: string[] };
250
  [key: string]: any;
251
}
252
```