0
# @npmcli/arborist
1

2
@npmcli/arborist is a comprehensive Node.js library for managing dependency trees. It provides programmatic APIs for loading, analyzing, and manipulating JavaScript dependency structures with sophisticated resolution algorithms, serving as the core dependency resolution engine for npm CLI and other package management tools.
3

4
## Package Information
5

6
- **Package Name**: @npmcli/arborist
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install @npmcli/arborist`
10

11
## Core Imports
12

13
```javascript
14
const { Arborist, Node, Link, Edge, Shrinkwrap } = require('@npmcli/arborist');
15
```
16

17
For ES modules:
18

19
```javascript
20
import { Arborist, Node, Link, Edge, Shrinkwrap } from '@npmcli/arborist';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const Arborist = require('@npmcli/arborist');
27

28
// Create arborist instance
29
const arb = new Arborist({
30
  path: '/path/to/package/root'
31
});
32

33
// Load actual dependency tree from disk
34
const actualTree = await arb.loadActual();
35

36
// Build ideal tree from package.json and lockfiles
37
await arb.buildIdealTree({
38
  add: ['express@^4.18.0'],
39
  saveType: 'prod'
40
});
41

42
// Apply changes to disk
43
await arb.reify();
44
```
45

46
## Architecture
47

48
@npmcli/arborist is built around several key concepts:
49

50
- **Tree Types**: Manages three types of dependency trees - actual (on disk), virtual (from lockfiles), and ideal (desired state)
51
- **Core Classes**: Node, Link, and Edge objects represent packages, symbolic links, and dependency relationships
52
- **Resolution Engine**: Implements Node.js module resolution with advanced dependency management features
53
- **Lockfile Management**: Handles npm lockfile versions 1, 2, and 3 with bidirectional conversion
54
- **Workspace Support**: Full monorepo and workspace-aware dependency management
55

56
## Capabilities
57

58
### Core Arborist Operations
59

60
Primary dependency tree management operations including loading trees, building ideal states, and applying changes to disk.
61

62
```javascript { .api }
63
class Arborist {
64
  constructor(options?: ArboristOptions): Arborist;
65
  loadActual(options?: LoadOptions): Promise<Node>;
66
  loadVirtual(options?: LoadOptions): Promise<Node>;
67
  buildIdealTree(options?: BuildOptions): Promise<void>;
68
  reify(options?: ReifyOptions): Promise<void>;
69
  audit(options?: AuditOptions): Promise<AuditReport>;
70
  dedupe(options?: DedupeOptions): Promise<void>;
71
}
72

73
interface ArboristOptions {
74
  path?: string;
75
  cache?: string;
76
  registry?: string;
77
  dryRun?: boolean;
78
  force?: boolean;
79
  global?: boolean;
80
  installStrategy?: 'hoisted' | 'shallow';
81
  lockfileVersion?: 1 | 2 | 3 | null;
82
  workspaces?: string[];
83
  workspacesEnabled?: boolean;
84
}
85
```
86

87
[Core Arborist Operations](./arborist.md)
88

89
### Dependency Tree Navigation
90

91
Node-based tree structure with methods for navigating, querying, and manipulating package relationships in the dependency graph.
92

93
```javascript { .api }
94
class Node {
95
  constructor(options?: NodeOptions): Node;
96
  resolve(name: string): Node | undefined;
97
  matches(node: Node): boolean;
98
  satisfies(requested: Edge): boolean;
99
  querySelectorAll(query: string, opts?: QueryOptions): Node[];
100
  
101
  // Properties
102
  name: string;
103
  version: string;
104
  path: string;
105
  parent: Node | null;
106
  children: Map<string, Node>;
107
  edgesOut: Map<string, Edge>;
108
  edgesIn: Set<Edge>;
109
}
110
```
111

112
[Dependency Tree Navigation](./tree-navigation.md)
113

114
### Dependency Relationships
115

116
Edge objects representing dependency relationships between packages with comprehensive validation and type information.
117

118
```javascript { .api }
119
class Edge {
120
  constructor(options: EdgeOptions): Edge;
121
  satisfiedBy(node: Node): boolean;
122
  reload(hard?: boolean): void;
123
  
124
  // Properties
125
  name: string;
126
  type: 'prod' | 'dev' | 'optional' | 'peer' | 'peerOptional' | 'workspace';
127
  spec: string;
128
  from: Node;
129
  to: Node | null;
130
  valid: boolean;
131
  error: string | null;
132
}
133
```
134

135
[Dependency Relationships](./edges.md)
136

137
### Symbolic Links
138

139
Link objects for handling symbolic links within node_modules with proper target resolution and dependency delegation.
140

141
```javascript { .api }
142
class Link extends Node {
143
  constructor(options?: LinkOptions): Link;
144
  
145
  // Properties
146
  isLink: true;
147
  target: Node;
148
  resolved: string;
149
}
150
```
151

152
[Symbolic Links](./links.md)
153

154
### Lockfile Management
155

156
Shrinkwrap class for managing package-lock.json and npm-shrinkwrap.json files with support for multiple lockfile versions.
157

158
```javascript { .api }
159
class Shrinkwrap {
160
  constructor(options?: ShrinkwrapOptions): Shrinkwrap;
161
  static load(options?: ShrinkwrapOptions): Promise<Shrinkwrap>;
162
  save(options?: SaveOptions): Promise<void>;
163
  get(nodePath: string): any;
164
  add(node: Node): void;
165
  
166
  // Properties
167
  data: object;
168
  lockfileVersion: number;
169
  filename: string;
170
  tree: Node | null;
171
}
172
```
173

174
[Lockfile Management](./shrinkwrap.md)
175

176
## Types
177

178
```javascript { .api }
179
interface LoadOptions {
180
  filter?: (node: Node, kidName: string) => boolean;
181
  forceActual?: boolean;
182
}
183

184
interface BuildOptions {
185
  add?: string[];
186
  rm?: string[];
187
  update?: boolean | { all?: boolean; names?: string[] };
188
  saveType?: 'prod' | 'dev' | 'optional' | 'peer' | 'peerOptional';
189
  saveBundle?: boolean;
190
  prune?: boolean;
191
  preferDedupe?: boolean;
192
  legacyBundling?: boolean;
193
}
194

195
interface ReifyOptions {
196
  save?: boolean;
197
  dryRun?: boolean;
198
  omit?: string[];
199
  include?: string[];
200
}
201

202
interface AuditOptions {
203
  fix?: boolean;
204
  packageLock?: boolean;
205
  filterSet?: Set<Node>;
206
}
207

208
interface NodeOptions {
209
  path?: string;
210
  parent?: Node;
211
  name?: string;
212
  root?: Node;
213
  realpath?: string;
214
  children?: object;
215
  dev?: boolean;
216
  optional?: boolean;
217
  peer?: boolean;
218
  extraneous?: boolean;
219
}
220

221
interface EdgeOptions {
222
  type: 'prod' | 'dev' | 'optional' | 'peer' | 'peerOptional' | 'workspace';
223
  name: string;
224
  spec: string;
225
  from: Node;
226
  accept?: string;
227
}
228

229
interface LinkOptions extends NodeOptions {
230
  target?: Node;
231
  realpath: string;
232
}
233

234
interface ShrinkwrapOptions {
235
  path?: string;
236
  lockfileVersion?: 1 | 2 | 3;
237
  indent?: number;
238
  newline?: string;
239
}
240

241
interface QueryOptions {
242
  all?: boolean;
243
}
244

245
interface SaveOptions {
246
  format?: boolean;
247
}
248
```