0
# Rush SDK
1

2
Rush SDK is a lightweight proxy API for accessing the @microsoft/rush-lib APIs. It acts as a smart loader that automatically resolves to the correct version of @microsoft/rush-lib based on the Rush workspace configuration, handling module loading, version compatibility, and runtime binding across different execution contexts.
3

4
**Note**: Rush SDK transparently re-exports all public APIs from @microsoft/rush-lib without duplication. The API declarations are identical to the corresponding version of @microsoft/rush-lib.
5

6
## Package Information
7

8
- **Package Name**: @rushstack/rush-sdk
9
- **Package Type**: npm
10
- **Language**: TypeScript
11
- **Installation**: `npm install @rushstack/rush-sdk`
12

13
## Core Imports
14

15
```typescript
16
import { RushConfiguration, Rush } from "@rushstack/rush-sdk";
17
```
18

19
For CommonJS:
20

21
```javascript
22
const { RushConfiguration, Rush } = require("@rushstack/rush-sdk");
23
```
24

25
For loader API:
26

27
```typescript
28
import { RushSdkLoader } from "@rushstack/rush-sdk/loader";
29
```
30

31
## Basic Usage
32

33
```typescript
34
import { RushConfiguration } from "@rushstack/rush-sdk";
35

36
// Load Rush configuration from current directory
37
const config = RushConfiguration.loadFromDefaultLocation();
38
console.log(`Rush version: ${config.rushVersion}`);
39
console.log(`Projects: ${config.projects.length}`);
40

41
// Access project information
42
for (const project of config.projects) {
43
  console.log(`${project.packageName} at ${project.projectRelativeFolder}`);
44
}
45
```
46

47
## Architecture
48

49
Rush SDK is built around several key components:
50

51
- **Proxy Architecture**: Transparently re-exports all @microsoft/rush-lib APIs without duplication
52
- **Smart Loading**: Supports 5 different loading scenarios for different execution contexts
53
- **Version Resolution**: Automatically loads the correct rush-lib version matching the workspace's rush.json
54
- **Runtime Binding**: Ensures the same @microsoft/rush-lib instance is shared across plugins and tools
55
- **Internal API Access**: Provides access to bundled internal modules through webpack stub mechanism
56
- **Progress Monitoring**: Loader API provides installation progress callbacks and cancellation support
57

58
### Loading Scenarios
59

60
1. **Rush Plugins**: Rush plugins receive a pre-loaded instance from the Rush host process
61
2. **Unit Tests**: Resolves to locally installed @microsoft/rush-lib in devDependencies
62
3. **Child Processes**: Inherits Rush installation via `_RUSH_LIB_PATH` environment variable
63
4. **Monorepo Tools**: Automatically invokes install-run-rush.js to load compatible version
64
5. **Manual Loading**: Advanced loader API with explicit control and progress monitoring
65

66
## Capabilities
67

68
### Rush SDK Core APIs
69

70
Rush SDK re-exports all public APIs from @microsoft/rush-lib. The main entry point provides access to core Rush functionality.
71

72
```typescript { .api }
73
// All @microsoft/rush-lib exports are available through rush-sdk
74
export * from '@microsoft/rush-lib';
75

76
// Additional rush-sdk specific API for internal module loading
77
export function _rushSdk_loadInternalModule(srcImportPath: string): unknown;
78
```
79

80
Key re-exported classes include:
81

82
```typescript { .api }
83
class Rush {
84
  static readonly version: string;
85
  static ensureRushVersionIsCompatible(rushVersion: string): void;
86
}
87

88
class RushConstants {
89
  static readonly rushJsonFilename: string;
90
  static readonly rushLinkJsonFilename: string;
91
  static readonly commonFolderName: string;
92
  static readonly nodeModulesFolderName: string;
93
}
94
```
95

96
### Rush Configuration Management
97

98
Core Rush workspace configuration management including rush.json parsing, project discovery, and workspace structure access. These APIs are re-exported from @microsoft/rush-lib.
99

100
```typescript { .api }
101
class RushConfiguration {
102
  static loadFromDefaultLocation(): RushConfiguration;
103
  static loadFromConfigurationFile(rushJsonFilename: string): RushConfiguration;
104
  static tryFindRushJsonLocation(startingFolder: string, options?: ITryFindRushJsonLocationOptions): string | undefined;
105
  readonly rushVersion: string;
106
  readonly projects: ReadonlyArray<RushConfigurationProject>;
107
  readonly projectsByName: ReadonlyMap<string, RushConfigurationProject>;
108
  readonly commonFolder: string;
109
  readonly rushJsonFolder: string;
110
  readonly packageManager: string;
111
  readonly packageManagerToolVersion: string;
112
}
113

114
class RushConfigurationProject {
115
  readonly packageName: string;
116
  readonly projectRelativeFolder: string;
117
  readonly projectFolder: string;
118
  readonly packageJson: IPackageJson;
119
  readonly shouldPublish: boolean;
120
  readonly reviewCategory: string;
121
  readonly localDependencies: ReadonlyArray<RushConfigurationProject>;
122
}
123

124
interface ITryFindRushJsonLocationOptions {
125
  showVerbose?: boolean;
126
}
127
```
128

129
[Configuration Management](./configuration.md)
130

131
### Package Management
132

133
Package manager abstraction and configuration for npm, pnpm, and yarn including installation options and dependency management. These APIs are re-exported from @microsoft/rush-lib.
134

135
```typescript { .api }
136
abstract class PackageManager {
137
  readonly name: PackageManagerName;
138
  readonly version: string;
139
}
140

141
type PackageManagerName = 'npm' | 'pnpm' | 'yarn';
142

143
class NpmOptionsConfiguration extends PackageManagerOptionsConfigurationBase {
144
  readonly environmentVariables: ReadonlyMap<string, string>;
145
}
146

147
class PnpmOptionsConfiguration extends PackageManagerOptionsConfigurationBase {
148
  readonly environmentVariables: ReadonlyMap<string, string>;
149
  readonly pnpmStorePath?: string;
150
  readonly resolutionMode?: PnpmResolutionMode;
151
}
152

153
class YarnOptionsConfiguration extends PackageManagerOptionsConfigurationBase {
154
  readonly environmentVariables: ReadonlyMap<string, string>;
155
}
156

157
abstract class PackageManagerOptionsConfigurationBase {
158
  readonly environmentVariables: ReadonlyMap<string, string>;
159
}
160

161
type PnpmResolutionMode = 'highest' | 'time-based' | 'lowest-direct';
162
```
163

164
[Package Management](./package-management.md)
165

166
### Build Operations and Change Detection
167

168
Build operation management, incremental builds, and change detection for efficient CI/CD workflows. These APIs are re-exported from @microsoft/rush-lib.
169

170
```typescript { .api }
171
class Operation {
172
  readonly name: string;
173
  readonly status: OperationStatus;
174
  readonly dependencies: ReadonlySet<Operation>;
175
  executeAsync(): Promise<OperationStatus>;
176
}
177

178
enum OperationStatus {
179
  Executing = 'executing',
180
  Success = 'success',
181
  SuccessWithWarning = 'success:warning',
182
  Failure = 'failure',
183
  Blocked = 'blocked',
184
  Skipped = 'skipped'
185
}
186

187
class ChangeManager {
188
  static hasChanges(project: RushConfigurationProject): boolean;
189
}
190

191
class ProjectChangeAnalyzer {
192
  static getChangedProjectsAsync(options: IGetChangedProjectsOptions): Promise<Set<RushConfigurationProject>>;
193
}
194

195
interface IGetChangedProjectsOptions {
196
  targetBranchName?: string;
197
  enableFiltering?: boolean;
198
  verbose?: boolean;
199
}
200
```
201

202
[Build Operations](./build-operations.md)
203

204
### Version Management
205

206
Version policies, bumping strategies, and coordinated publishing across monorepo projects. These APIs are re-exported from @microsoft/rush-lib.
207

208
```typescript { .api }
209
abstract class VersionPolicy {
210
  readonly policyName: string;
211
  readonly definitionName: VersionPolicyDefinitionName;
212
  abstract bump(bumpType?: BumpType): void;
213
}
214

215
class IndividualVersionPolicy extends VersionPolicy {
216
  readonly lockedMajor?: number;
217
}
218

219
class LockStepVersionPolicy extends VersionPolicy {
220
  readonly version: string;
221
  readonly nextBump?: BumpType;
222
}
223

224
enum BumpType {
225
  prerelease = 'prerelease',
226
  patch = 'patch',
227
  minor = 'minor',
228
  major = 'major'
229
}
230

231
enum VersionPolicyDefinitionName {
232
  lockStepVersion = 'lockStepVersion',
233
  individualVersion = 'individualVersion'
234
}
235

236
class VersionPolicyConfiguration {
237
  static loadFromFile(jsonFilename: string): VersionPolicyConfiguration;
238
  readonly versionPolicies: ReadonlyArray<VersionPolicy>;
239
}
240
```
241

242
[Version Management](./version-management.md)
243

244
### Manual Loading API
245

246
Advanced loader API for explicit control over Rush engine loading with progress monitoring and cancellation support. This API is specific to Rush SDK and available via `@rushstack/rush-sdk/loader`.
247

248
```typescript { .api }
249
class RushSdkLoader {
250
  static readonly isLoaded: boolean;
251
  static loadAsync(options?: ILoadSdkAsyncOptions): Promise<void>;
252
}
253

254
interface ILoadSdkAsyncOptions {
255
  rushJsonSearchFolder?: string;
256
  abortSignal?: AbortSignal;
257
  onNotifyEvent?: SdkNotifyEventCallback;
258
}
259

260
interface ISdkCallbackEvent {
261
  logMessage: IProgressBarCallbackLogMessage | undefined;
262
  progressPercent: number | undefined;
263
}
264

265
interface IProgressBarCallbackLogMessage {
266
  text: string;
267
  kind: 'info' | 'debug';
268
}
269

270
type SdkNotifyEventCallback = (sdkEvent: ISdkCallbackEvent) => void;
271
```
272

273
[Manual Loading](./manual-loading.md)
274

275
### Configuration Files Management
276

277
Management of Rush configuration files including common-versions.json, approved packages, and workspace settings. These APIs are re-exported from @microsoft/rush-lib.
278

279
```typescript { .api }
280
class CommonVersionsConfiguration {
281
  readonly filePath: string;
282
  readonly preferredVersions: ReadonlyMap<string, string>;
283
  save(): void;
284
}
285

286
class ApprovedPackagesConfiguration {
287
  readonly approvedPackages: ReadonlyArray<ApprovedPackagesItem>;
288
  addOrUpdatePackage(packageName: string, reviewCategory: string): ApprovedPackagesItem;
289
}
290

291
class ApprovedPackagesItem {
292
  readonly packageName: string;
293
  readonly allowedCategories: ReadonlySet<string>;
294
}
295

296
class ExperimentsConfiguration {
297
  readonly configuration: ReadonlyMap<string, boolean>;
298
  isFeatureEnabled(featureName: string): boolean;
299
}
300
```
301

302
[Configuration Files](./configuration-files.md)
303

304
### Internal API Access
305

306
Access to internal @microsoft/rush-lib modules through webpack stub mechanism for advanced scenarios.
307

308
```typescript { .api }
309
function _rushSdk_loadInternalModule(srcImportPath: string): unknown;
310
```
311

312
**Usage Examples:**
313

314
```typescript
315
// WARNING: Internal APIs may change - use at your own risk
316
import { _rushSdk_loadInternalModule } from "@rushstack/rush-sdk";
317

318
// Load internal module using the source import path
319
const GitEmailPolicy = _rushSdk_loadInternalModule("lib/logic/policy/GitEmailPolicy");
320
```
321

322
Alternatively, you can use path-based imports with stub files:
323

324
```typescript
325
// Path-based import of internal API using stub files
326
import { GitEmailPolicy } from "@rushstack/rush-sdk/lib/logic/policy/GitEmailPolicy";
327
console.log(GitEmailPolicy.getEmailExampleLines(config));
328
```
329

330
**Note**: Internal API access requires that the loaded rush-lib version supports the `_RushInternals` API. If version mismatch occurs, an error will be thrown.
331

332
## Types
333

334
```typescript { .api }
335
// Core types re-exported from @microsoft/rush-lib
336
interface IPackageJson {
337
  name: string;
338
  version: string;
339
  dependencies?: Record<string, string>;
340
  devDependencies?: Record<string, string>;
341
  peerDependencies?: Record<string, string>;
342
  optionalDependencies?: Record<string, string>;
343
}
344

345
enum DependencyType {
346
  Regular = 'dependencies',
347
  Dev = 'devDependencies',
348
  Optional = 'optionalDependencies',
349
  Peer = 'peerDependencies'
350
}
351

352
// Loader-specific types (from @rushstack/rush-sdk/loader)
353
type SdkNotifyEventCallback = (sdkEvent: ISdkCallbackEvent) => void;
354

355
interface IProgressBarCallbackLogMessage {
356
  text: string;
357
  kind: 'info' | 'debug';
358
}
359

360
interface ILaunchOptions {
361
  isManaged?: boolean;
362
  alreadyReportedNodeTooNewError?: boolean;
363
}
364

365
// Re-exported plugin framework types
366
interface IRushPlugin {
367
  pluginName: string;
368
  apply(rushSession: RushSession, rushConfiguration: RushConfiguration): void;
369
}
370

371
interface IRushSessionOptions {
372
  terminalProvider?: ITerminalProvider;
373
  getIsDebugMode?: () => boolean;
374
}
375
```