0
# Package Management
1

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

4
## Capabilities
5

6
### Package Detection
7

8
Automatically detects and returns all packages in the workspace.
9

10
```typescript { .api }
11
/**
12
 * Detects and returns project graph and file mapping for the workspace
13
 * @param rootDir - Root directory to search (defaults to workspace root)
14
 * @returns Promise resolving to project graph and file map
15
 */
16
function detectProjects(rootDir?: string): Promise<{
17
  projectGraph: ProjectGraphWithPackages;
18
  projectFileMap: ProjectFileMap;
19
}>;
20
```
21

22
**Usage Example:**
23

24
```typescript
25
import { detectProjects } from "lerna/utils";
26

27
// Detect all packages in current workspace
28
const { projectGraph, projectFileMap } = await detectProjects();
29

30
// Detect packages from specific directory
31
const { projectGraph, projectFileMap } = await detectProjects("/path/to/workspace");
32

33
// Get package names from project graph
34
const packageNames = Object.values(projectGraph.nodes)
35
  .filter(node => node.package)
36
  .map(node => node.package!.name);
37

38
console.log(packageNames);
39
```
40

41
### List Packages
42

43
Display all packages in the workspace with various formatting options.
44

45
```bash { .api }
46
# List all packages
47
lerna list
48
lerna ls     # Alias for 'list'  
49
lerna la     # Alias for 'list --all'
50
lerna ll     # Alias for 'list --long'
51

52
# List packages with additional information
53
lerna list --long
54

55
# List packages as JSON
56
lerna list --json
57

58
# List only changed packages
59
lerna list --since HEAD~1
60

61
# List packages in specific scope
62
lerna list --scope="@myorg/*"
63

64
# List packages excluding specific scope
65
lerna list --ignore="@myorg/internal-*"
66
```
67

68
The `lerna list` command supports the following options:
69

70
- `--json` - Output as JSON array
71
- `--ndjson` - Output as newline-delimited JSON
72
- `--long` - Show extended information (version, location)
73
- `--parseable` - Show parseable output (similar to npm ls --parseable)
74
- `--toposort` - Sort packages in topological order
75
- `--graph` - Show dependency graph
76
- `--all` - Include private packages (default behavior)
77
- `--since <ref>` - List packages changed since ref
78
- `--scope <glob>` - Include packages matching glob
79
- `--ignore <glob>` - Exclude packages matching glob
80

81
### Clean Packages
82

83
Remove node_modules directories from all packages.
84

85
```bash { .api }
86
# Remove node_modules from all packages
87
lerna clean
88

89
# Remove node_modules with confirmation prompt
90
lerna clean --yes
91
```
92

93
**Usage Example:**
94

95
```bash
96
# Clean all packages and confirm deletion
97
lerna clean
98

99
# Clean all packages without confirmation
100
lerna clean --yes
101

102
# Clean specific scoped packages
103
lerna clean --scope="@myorg/*"
104
```
105

106
## Package Structure
107

108
```typescript { .api }
109
interface Package {
110
  /** Package name from package.json */
111
  name: string;
112
  /** Package version from package.json */
113
  version: string;
114
  /** Absolute path to package directory */
115
  location: string;
116
  /** Whether package is marked as private */
117
  private?: boolean;
118
  /** npm scripts defined in package.json */
119
  scripts?: Record<string, string>;
120
  /** Production dependencies */
121
  dependencies?: Record<string, string>;
122
  /** Development dependencies */
123
  devDependencies?: Record<string, string>;
124
  /** Peer dependencies */
125
  peerDependencies?: Record<string, string>;
126
  /** Optional dependencies */
127
  optionalDependencies?: Record<string, string>;
128
  /** Bundled dependencies */
129
  bundleDependencies?: string[];
130
  /** Package.json contents */
131
  toJSON(): PackageJson;
132
  /** Get package manifest */
133
  get(key: string): any;
134
  /** Set package manifest property */
135
  set(key: string, value: any): void;
136
}
137

138
interface PackageJson {
139
  name: string;
140
  version: string;
141
  description?: string;
142
  main?: string;
143
  scripts?: Record<string, string>;
144
  dependencies?: Record<string, string>;
145
  devDependencies?: Record<string, string>;
146
  peerDependencies?: Record<string, string>;
147
  [key: string]: any;
148
}
149
```
150

151
## Filtering Options
152

153
Lerna provides powerful filtering capabilities that work across most commands:
154

155
### Scope Filtering
156

157
```bash
158
# Include packages matching pattern
159
--scope="pattern"
160

161
# Multiple scope patterns
162
--scope="@myorg/*" --scope="utilities-*"
163

164
# Exclude packages matching pattern  
165
--ignore="pattern"
166

167
# Multiple ignore patterns
168
--ignore="@myorg/internal-*" --ignore="*-test"
169
```
170

171
### Change-based Filtering
172

173
```bash
174
# Only packages changed since ref
175
--since="HEAD~1"
176
--since="v1.0.0"
177
--since="main"
178

179
# Include dependencies of changed packages
180
--include-dependents
181

182
# Include dependencies that changed packages depend on
183
--include-dependencies
184

185
# Include packages affected by changes (both directions)
186
--include-merged-tags
187
```
188

189
### Private Package Handling
190

191
```bash
192
# Exclude private packages (private: true in package.json)
193
--no-private
194

195
# Include only private packages
196
--private
197
```