0
# Package Management
1

2
Package manager abstraction and configuration for npm, pnpm, and yarn including installation options and dependency management.
3

4
**Note**: All APIs in this document are re-exported from @microsoft/rush-lib through @rushstack/rush-sdk.
5

6
## Capabilities
7

8
### PackageManager
9

10
Abstract base class for package manager implementations with unified API across npm, pnpm, and yarn.
11

12
```typescript { .api }
13
/**
14
 * Abstract base class for package manager implementations
15
 */
16
abstract class PackageManager {
17
  /** Package manager name (npm, pnpm, yarn) */
18
  readonly name: string;
19
  
20
  /** Package manager version */
21
  readonly version: string;
22
  
23
  /** Common folder path */
24
  readonly commonFolder: string;
25
  
26
  /** Install all dependencies */
27
  abstract installAsync(options: IInstallManagerOptions): Promise<void>;
28
  
29
  /** Check if shrinkwrap file exists */
30
  abstract isValidShrinkwrapFile(shrinkwrapFilePath: string): boolean;
31
  
32
  /** Get shrinkwrap file path */
33
  abstract getShrinkwrapFilePath(projectFolder: string): string;
34
  
35
  /** Parse shrinkwrap file */
36
  abstract parseShrinkwrapFile(shrinkwrapFilePath: string): DependencySpecifier | undefined;
37
}
38

39
interface IInstallManagerOptions {
40
  /** Skip policy checks */
41
  bypassPolicy?: boolean;
42
  
43
  /** Allow shrinkwrap updates */
44
  allowShrinkwrapUpdates?: boolean;
45
  
46
  /** Maximum install attempts */
47
  maxInstallAttempts?: number;
48
  
49
  /** Network concurrency limit */
50
  networkConcurrency?: number;
51
  
52
  /** Check store integrity */
53
  checkRuntimeShrinkwrap?: boolean;
54
}
55
```
56

57
**Usage Examples:**
58

59
```typescript
60
import { RushConfiguration } from "@rushstack/rush-sdk";
61

62
const config = loadFromDefaultLocation();
63
const packageManager = config.packageManager;
64

65
console.log(`Using ${packageManager.name} version ${packageManager.version}`);
66

67
// Install dependencies
68
await packageManager.installAsync({
69
  allowShrinkwrapUpdates: true,
70
  maxInstallAttempts: 3
71
});
72
```
73

74
### NPM Configuration
75

76
Configuration options specific to npm package manager.
77

78
```typescript { .api }
79
/**
80
 * NPM-specific configuration options
81
 */
82
class NpmOptionsConfiguration {
83
  /** Environment variables to set during npm operations */
84
  readonly environmentVariables: ReadonlyMap<string, string>;
85
  
86
  /** NPM registry URL */
87
  readonly registry?: string;
88
  
89
  /** Additional command line arguments */
90
  readonly additionalArgs: ReadonlyArray<string>;
91
  
92
  /** Cache folder path */
93
  readonly cacheFolder?: string;
94
  
95
  /** Temporary folder path */
96
  readonly tmpFolder?: string;
97
}
98
```
99

100
### PNPM Configuration
101

102
Configuration options specific to pnpm package manager.
103

104
```typescript { .api }
105
/**
106
 * PNPM-specific configuration options  
107
 */
108
class PnpmOptionsConfiguration {
109
  /** Environment variables to set during pnpm operations */
110
  readonly environmentVariables: ReadonlyMap<string, string>;
111
  
112
  /** PNPM store path */
113
  readonly pnpmStorePath?: string;
114
  
115
  /** Prevent store pruning */
116
  readonly preventManualShrinkwrapChanges: boolean;
117
  
118
  /** Use frozen lockfile */
119
  readonly useFrozenLockfileForInstall: boolean;
120
  
121
  /** Additional command line arguments */
122
  readonly additionalArgs: ReadonlyArray<string>;
123
  
124
  /** Global folder path */
125
  readonly globalFolder?: string;
126
  
127
  /** Cache folder path */
128
  readonly cacheFolder?: string;
129
  
130
  /** State folder path */
131
  readonly stateFolder?: string;
132
}
133
```
134

135
### Yarn Configuration
136

137
Configuration options specific to yarn package manager.
138

139
```typescript { .api }
140
/**
141
 * Yarn-specific configuration options
142
 */
143
class YarnOptionsConfiguration {
144
  /** Environment variables to set during yarn operations */
145
  readonly environmentVariables: ReadonlyMap<string, string>;
146
  
147
  /** Ignore optional dependencies */
148
  readonly ignoreOptionalDependencies: boolean;
149
  
150
  /** Network timeout in milliseconds */
151
  readonly networkTimeout?: number;
152
  
153
  /** Additional command line arguments */
154
  readonly additionalArgs: ReadonlyArray<string>;
155
  
156
  /** Cache folder path */
157
  readonly cacheFolder?: string;
158
}
159
```
160

161
**Usage Examples:**
162

163
```typescript
164
import { RushConfiguration } from "@rushstack/rush-sdk";
165

166
const config = RushConfiguration.loadFromDefaultLocation();
167

168
// Access package manager specific options
169
if (config.packageManager === 'pnpm') {
170
  const pnpmOptions = config.pnpmOptions;
171
  console.log(`PNPM store path: ${pnpmOptions.pnpmStorePath}`);
172
  console.log(`Frozen lockfile: ${pnpmOptions.useFrozenLockfileForInstall}`);
173
}
174

175
if (config.packageManager === 'npm') {
176
  const npmOptions = config.npmOptions;
177
  console.log(`NPM registry: ${npmOptions.registry}`);
178
  console.log(`Cache folder: ${npmOptions.cacheFolder}`);
179
}
180

181
if (config.packageManager === 'yarn') {
182
  const yarnOptions = config.yarnOptions;
183
  console.log(`Network timeout: ${yarnOptions.networkTimeout}`);
184
  console.log(`Ignore optional deps: ${yarnOptions.ignoreOptionalDependencies}`);
185
}
186
```
187

188
### Package JSON Management
189

190
Utilities for reading and manipulating package.json files with dependency management.
191

192
```typescript { .api }
193
/**
194
 * Utilities for editing package.json files
195
 */
196
class PackageJsonEditor {
197
  /** Load package.json from file path */
198
  static load(filePath: string): PackageJsonEditor;
199
  
200
  /** File path of the package.json */
201
  readonly filePath: string;
202
  
203
  /** Parsed package.json data */
204
  readonly packageJson: IPackageJson;
205
  
206
  /** Add or update a dependency */
207
  addOrUpdateDependency(
208
    packageName: string, 
209
    newVersion: string, 
210
    dependencyType: DependencyType
211
  ): void;
212
  
213
  /** Remove a dependency */
214
  tryRemoveDependency(packageName: string, dependencyType: DependencyType): boolean;
215
  
216
  /** Get dependency version */
217
  tryGetDependency(packageName: string): PackageJsonDependency | undefined;
218
  
219
  /** Save changes to disk */
220
  saveIfModified(): boolean;
221
}
222

223
/**
224
 * Represents a package.json dependency
225
 */
226
class PackageJsonDependency {
227
  /** Package name */
228
  readonly name: string;
229
  
230
  /** Version specifier */
231
  readonly version: string;
232
  
233
  /** Dependency type */
234
  readonly dependencyType: DependencyType;
235
  
236
  /** Additional metadata */
237
  readonly dependencyMeta: PackageJsonDependencyMeta;
238
}
239

240
class PackageJsonDependencyMeta {
241
  /** Whether dependency is injected by Rush */
242
  readonly injected?: boolean;
243
}
244

245
enum DependencyType {
246
  Regular = "dependencies",
247
  Dev = "devDependencies",
248
  Optional = "optionalDependencies", 
249
  Peer = "peerDependencies"
250
}
251
```
252

253
**Usage Examples:**
254

255
```typescript
256
import { PackageJsonEditor, DependencyType } from "@rushstack/rush-sdk";
257

258
// Load and edit package.json
259
const editor = PackageJsonEditor.load("./package.json");
260

261
// Add a new dependency
262
editor.addOrUpdateDependency("lodash", "^4.17.21", DependencyType.Regular);
263

264
// Update a dev dependency
265
editor.addOrUpdateDependency("typescript", "^4.5.0", DependencyType.Dev);
266

267
// Check if dependency exists
268
const dep = editor.tryGetDependency("react");
269
if (dep) {
270
  console.log(`React version: ${dep.version}`);
271
}
272

273
// Remove a dependency
274
const removed = editor.tryRemoveDependency("unused-package", DependencyType.Regular);
275
console.log(`Removed: ${removed}`);
276

277
// Save changes
278
const modified = editor.saveIfModified();
279
console.log(`Package.json modified: ${modified}`);
280
```
281

282
### Dependency Resolution
283

284
Advanced dependency resolution and shrinkwrap management.
285

286
```typescript { .api }
287
/**
288
 * Dependency specifier for resolving package versions
289
 */
290
class DependencySpecifier {
291
  /** Package name */
292
  readonly packageName: string;
293
  
294
  /** Version range */
295
  readonly versionSpecifier: string;
296
  
297
  /** Create from string like "package@1.0.0" */
298
  static parse(specifier: string): DependencySpecifier;
299
  
300
  /** Check if version satisfies this specifier */
301
  versionIsCompatible(version: string): boolean;
302
}
303
```