0
# Manual Loading API
1

2
Advanced loader API for explicit control over Rush engine loading with progress monitoring and cancellation support.
3

4
## Capabilities
5

6
### RushSdkLoader
7

8
Main loader class that provides explicit control over when and how the Rush engine is loaded.
9

10
```typescript { .api }
11
/**
12
 * Provides operations that control how the @microsoft/rush-lib engine is located and loaded
13
 */
14
class RushSdkLoader {
15
  /** Returns true if the Rush engine has already been loaded */
16
  static readonly isLoaded: boolean;
17
  
18
  /** 
19
   * Manually load the Rush engine based on rush.json found for rushJsonSearchFolder
20
   * Throws an exception if isLoaded is already true
21
   */
22
  static loadAsync(options?: ILoadSdkAsyncOptions): Promise<void>;
23
}
24
```
25

26
**Usage Examples:**
27

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

31
// Basic loading
32
if (!RushSdkLoader.isLoaded) {
33
  await RushSdkLoader.loadAsync();
34
}
35

36
// Load from specific folder
37
await RushSdkLoader.loadAsync({
38
  rushJsonSearchFolder: "/path/to/my-repo/apps/my-app"
39
});
40

41
// With progress monitoring
42
await RushSdkLoader.loadAsync({
43
  rushJsonSearchFolder: process.cwd(),
44
  onNotifyEvent: (event) => {
45
    if (event.logMessage) {
46
      console.log(event.logMessage.text);
47
    }
48
    if (event.progressPercent !== undefined) {
49
      console.log(`Progress: ${event.progressPercent}%`);
50
    }
51
  }
52
});
53

54
// After loading, use regular Rush SDK APIs
55
const rushSdk = require("@rushstack/rush-sdk");
56
const config = rushSdk.RushConfiguration.loadFromDefaultLocation();
57
```
58

59
### Loading Options
60

61
Configuration options for the manual loading process.
62

63
```typescript { .api }
64
/**
65
 * Options for RushSdkLoader.loadAsync
66
 */
67
interface ILoadSdkAsyncOptions {
68
  /** 
69
   * The folder to start from when searching for rush.json
70
   * If not found, each parent folder will be searched
71
   * Defaults to process.cwd()
72
   */
73
  rushJsonSearchFolder?: string;
74
  
75
  /** 
76
   * A cancellation token that the caller can use to abort the operation
77
   */
78
  abortSignal?: AbortSignal;
79
  
80
  /** 
81
   * Allows the caller to monitor the progress of the operation
82
   */
83
  onNotifyEvent?: SdkNotifyEventCallback;
84
}
85

86
/**
87
 * Callback function type for progress notifications
88
 */
89
type SdkNotifyEventCallback = (sdkEvent: ISdkCallbackEvent) => void;
90
```
91

92
**Usage Examples:**
93

94
```typescript
95
import { RushSdkLoader } from "@rushstack/rush-sdk/loader";
96

97
// With cancellation support
98
const abortController = new AbortController();
99
setTimeout(() => abortController.abort(), 30000); // Cancel after 30 seconds
100

101
try {
102
  await RushSdkLoader.loadAsync({
103
    rushJsonSearchFolder: "/path/to/repo",
104
    abortSignal: abortController.signal,
105
    onNotifyEvent: (event) => {
106
      if (event.logMessage?.kind === 'info') {
107
        console.log(`INFO: ${event.logMessage.text}`);
108
      }
109
    }
110
  });
111
} catch (error) {
112
  if (error.name === 'AbortError') {
113
    console.log('Loading was cancelled');
114
  } else {
115
    throw error;
116
  }
117
}
118
```
119

120
### Progress Events
121

122
Event data provided during the loading process for monitoring and user feedback.
123

124
```typescript { .api }
125
/**
126
 * Event data for onNotifyEvent callback
127
 */
128
interface ISdkCallbackEvent {
129
  /** 
130
   * Log message to display, or undefined if no message
131
   */
132
  logMessage: IProgressBarCallbackLogMessage | undefined;
133
  
134
  /** 
135
   * Progress percentage (0-100) if a long-running operation is active,
136
   * undefined if no progress tracking is available
137
   */
138
  progressPercent: number | undefined;
139
}
140

141
/**
142
 * Log message structure
143
 */
144
interface IProgressBarCallbackLogMessage {
145
  /** The message text, may contain newlines */
146
  text: string;
147
  
148
  /** The type of message */
149
  kind: "info" | "debug";
150
}
151
```
152

153
**Usage Examples:**
154

155
```typescript
156
import { RushSdkLoader, ISdkCallbackEvent } from "@rushstack/rush-sdk/loader";
157

158
// Advanced progress monitoring
159
function displayProgress(event: ISdkCallbackEvent): void {
160
  if (event.logMessage) {
161
    const prefix = event.logMessage.kind === 'info' ? '[INFO]' : '[DEBUG]';
162
    console.log(`${prefix} ${event.logMessage.text}`);
163
  }
164
  
165
  if (event.progressPercent !== undefined) {
166
    const progressBar = '='.repeat(Math.floor(event.progressPercent / 2));
167
    const spaces = ' '.repeat(50 - progressBar.length);
168
    console.log(`[${progressBar}${spaces}] ${event.progressPercent.toFixed(1)}%`);
169
  }
170
}
171

172
await RushSdkLoader.loadAsync({
173
  onNotifyEvent: displayProgress
174
});
175
```
176

177
## Loading Scenarios
178

179
The Rush SDK supports five different loading scenarios:
180

181
### 1. Rush Plugin Context
182
Rush's PluginManager pre-initializes the SDK with its own instance. The global variable `___rush___rushLibModule` is set before loading plugins.
183

184
### 2. Unit Testing Context  
185
Projects with @microsoft/rush-lib in devDependencies will use their local instance for testing.
186

187
### 3. Child Process Context
188
Tools invoked by Rush inherit the installation via the `_RUSH_LIB_PATH` environment variable.
189

190
### 4. Standalone Tools Context
191
Scripts and tools automatically discover Rush via rush.json and use install-run-rush.js to load the appropriate version.
192

193
### 5. Manual Loading Context
194
Explicit control using `RushSdkLoader.loadAsync()` with full progress monitoring and cancellation support.
195

196
## Error Handling
197

198
```typescript
199
import { RushSdkLoader } from "@rushstack/rush-sdk/loader";
200

201
try {
202
  await RushSdkLoader.loadAsync({
203
    rushJsonSearchFolder: "/invalid/path"
204
  });
205
} catch (error) {
206
  if (error.name === 'AbortError') {
207
    console.log('Operation was cancelled');
208
  } else if (error.message.includes('Unable to find rush.json')) {
209
    console.log('Not in a Rush workspace');
210
  } else if (error.message.includes('failed to install')) {
211
    console.log('Failed to install Rush engine');
212
  } else {
213
    console.log(`Unexpected error: ${error.message}`);
214
  }
215
}
216
```
217

218
## Debug Support
219

220
Enable verbose logging by setting environment variables:
221

222
```bash
223
# Enable debug logging
224
export RUSH_SDK_DEBUG=1
225

226
# Alternative debug flag
227
export _RUSH_SDK_DEBUG=1
228
```
229

230
When debug logging is enabled, detailed information about the loading process will be printed to the console, including which scenario is being used and how the Rush engine was located.