0
# Configuration Files Management
1

2
Management of Rush configuration files including common-versions.json, approved packages, and workspace settings.
3

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

6
## Capabilities
7

8
### Common Versions Configuration
9

10
Management of the common-versions.json file for enforcing consistent dependency versions across the workspace.
11

12
```typescript { .api }
13
/**
14
 * Manages the common-versions.json configuration file
15
 */
16
class CommonVersionsConfiguration {
17
  /** Path to the common-versions.json file */
18
  readonly filePath: string;
19
  
20
  /** Preferred versions map from common-versions.json */
21
  readonly preferredVersions: ReadonlyMap<string, string>;
22
  
23
  /** Allowed alternative versions */
24
  readonly allowedAlternativeVersions: ReadonlyMap<string, ReadonlyArray<string>>;
25
  
26
  /** Load configuration from file */
27
  static loadFromFile(jsonFilename: string): CommonVersionsConfiguration;
28
  
29
  /** Get preferred version for package */
30
  getPreferredVersion(packageName: string): string | undefined;
31
  
32
  /** Set preferred version for package */
33
  setPreferredVersion(packageName: string, version: string): void;
34
  
35
  /** Remove preferred version for package */
36
  removePreferredVersion(packageName: string): boolean;
37
  
38
  /** Check if version is allowed */
39
  isVersionAllowed(packageName: string, version: string): boolean;
40
  
41
  /** Add allowed alternative version */
42
  addAllowedAlternativeVersion(packageName: string, version: string): void;
43
  
44
  /** Save changes to file */
45
  save(): void;
46
}
47
```
48

49
**Usage Examples:**
50

51
```typescript
52
import { CommonVersionsConfiguration, RushConfiguration } from "@rushstack/rush-sdk";
53

54
const config = RushConfiguration.loadFromDefaultLocation();
55
const commonVersions = CommonVersionsConfiguration.loadFromFile(
56
  path.join(config.commonRushConfigFolder, "common-versions.json")
57
);
58

59
// Check preferred versions
60
console.log("Preferred versions:");
61
for (const [packageName, version] of commonVersions.preferredVersions) {
62
  console.log(`  ${packageName}: ${version}`);
63
}
64

65
// Set a preferred version
66
commonVersions.setPreferredVersion("lodash", "^4.17.21");
67

68
// Check if version is allowed
69
const isAllowed = commonVersions.isVersionAllowed("react", "17.0.2");
70
console.log(`React 17.0.2 allowed: ${isAllowed}`);
71

72
// Add alternative version
73
commonVersions.addAllowedAlternativeVersion("typescript", "~4.4.0");
74

75
// Save changes
76
commonVersions.save();
77
```
78

79
### Approved Packages Configuration
80

81
Management of approved packages lists and review categories for security and compliance.
82

83
```typescript { .api }
84
/**
85
 * Manages the approved packages configuration
86
 */
87
class ApprovedPackagesConfiguration {
88
  /** Array of approved packages */
89
  readonly approvedPackages: ReadonlyArray<ApprovedPackagesItem>;
90
  
91
  /** Load configuration from file */
92
  static loadFromFile(jsonFilename: string): ApprovedPackagesConfiguration;
93
  
94
  /** Add or update an approved package */
95
  addOrUpdatePackage(packageName: string, reviewCategory: string): ApprovedPackagesItem;
96
  
97
  /** Try to get approved package by name */
98
  tryGetItemByPackageName(packageName: string): ApprovedPackagesItem | undefined;
99
  
100
  /** Check if package is approved */
101
  isPackageApproved(packageName: string): boolean;
102
  
103
  /** Remove approved package */
104
  removePackage(packageName: string): boolean;
105
  
106
  /** Save changes to file */
107
  save(): void;
108
}
109

110
/**
111
 * Represents an individual approved package entry
112
 */
113
class ApprovedPackagesItem {
114
  /** Package name */
115
  readonly packageName: string;
116
  
117
  /** Review category */
118
  readonly reviewCategory: string;
119
  
120
  /** Whether package is allowed */
121
  readonly allowedCategories: ReadonlySet<string>;
122
}
123

124
/**
125
 * Policy for approved packages enforcement
126
 */
127
class ApprovedPackagesPolicy {
128
  /** Whether policy is enabled */
129
  readonly enabled: boolean;
130
  
131
  /** Review categories that are allowed */
132
  readonly reviewCategories: ReadonlySet<string>;
133
  
134
  /** Default review category for new packages */
135
  readonly defaultReviewCategory: string;
136
  
137
  /** Check if package meets policy requirements */
138
  checkPackage(packageName: string, projectReviewCategory: string): boolean;
139
}
140
```
141

142
**Usage Examples:**
143

144
```typescript
145
import { ApprovedPackagesConfiguration, ApprovedPackagesPolicy } from "@rushstack/rush-sdk";
146

147
// Load approved packages configuration
148
const approvedPackages = ApprovedPackagesConfiguration.loadFromFile(
149
  path.join(config.commonRushConfigFolder, "approved-packages.json")
150
);
151

152
// Check if package is approved
153
const isApproved = approvedPackages.isPackageApproved("lodash");
154
console.log(`Lodash approved: ${isApproved}`);
155

156
// List all approved packages
157
console.log("Approved packages:");
158
for (const item of approvedPackages.approvedPackages) {
159
  console.log(`  ${item.packageName} (${item.reviewCategory})`);
160
}
161

162
// Add new approved package
163
const newItem = approvedPackages.addOrUpdatePackage("react", "standard");
164
console.log(`Added: ${newItem.packageName}`);
165

166
// Get specific package info
167
const packageInfo = approvedPackages.tryGetItemByPackageName("typescript");
168
if (packageInfo) {
169
  console.log(`TypeScript category: ${packageInfo.reviewCategory}`);
170
}
171

172
// Save changes
173
approvedPackages.save();
174
```
175

176
### Experiments Configuration
177

178
Management of experimental feature flags and Rush behavior modifications.
179

180
```typescript { .api }
181
/**
182
 * Manages experimental features configuration
183
 */
184
class ExperimentsConfiguration {
185
  /** Map of experiment names to enabled status */
186
  readonly configuration: ReadonlyMap<string, boolean>;
187
  
188
  /** Load configuration from file */
189
  static loadFromFile(jsonFilename: string): ExperimentsConfiguration;
190
  
191
  /** Check if experiment is enabled */
192
  isFeatureEnabled(experimentName: string): boolean;
193
  
194
  /** Enable or disable an experiment */
195
  setFeatureEnabled(experimentName: string, enabled: boolean): void;
196
  
197
  /** Get all enabled experiments */
198
  getEnabledExperiments(): ReadonlyArray<string>;
199
  
200
  /** Save changes to file */
201
  save(): void;
202
}
203
```
204

205
**Usage Examples:**
206

207
```typescript
208
import { ExperimentsConfiguration } from "@rushstack/rush-sdk";
209

210
const experiments = ExperimentsConfiguration.loadFromFile(
211
  path.join(config.commonRushConfigFolder, "experiments.json")
212
);
213

214
// Check specific experiment
215
const buildCacheEnabled = experiments.isFeatureEnabled("buildCache");
216
console.log(`Build cache experiment: ${buildCacheEnabled}`);
217

218
// List enabled experiments
219
const enabled = experiments.getEnabledExperiments();
220
console.log(`Enabled experiments: ${enabled.join(", ")}`);
221

222
// Enable new experiment
223
experiments.setFeatureEnabled("newFeature", true);
224

225
// Save changes
226
experiments.save();
227
```
228

229
### Custom Tips Configuration
230

231
Configuration for custom tip messages and notifications displayed by Rush.
232

233
```typescript { .api }
234
/**
235
 * Manages custom tips configuration
236
 */
237
class CustomTipsConfiguration {
238
  /** Array of configured tips */
239
  readonly tips: ReadonlyArray<ICustomTip>;
240
  
241
  /** Load configuration from file */
242
  static loadFromFile(jsonFilename: string): CustomTipsConfiguration;
243
  
244
  /** Get tips by severity */
245
  getTipsBySeverity(severity: CustomTipSeverity): ReadonlyArray<ICustomTip>;
246
  
247
  /** Get tips by ID */
248
  getTipById(tipId: CustomTipId): ICustomTip | undefined;
249
}
250

251
/**
252
 * Individual custom tip configuration
253
 */
254
interface ICustomTip {
255
  /** Unique tip identifier */
256
  readonly tipId: CustomTipId;
257
  
258
  /** Tip message text */
259
  readonly message: string;
260
  
261
  /** Tip severity level */
262
  readonly severity: CustomTipSeverity;
263
  
264
  /** Tip type */
265
  readonly tipType: CustomTipType;
266
  
267
  /** Optional URL for more information */
268
  readonly url?: string;
269
}
270

271
/**
272
 * Custom tip identifiers
273
 */
274
enum CustomTipId {
275
  TIP_RUSH_CONSISTENT_VERSIONS = "TIP_RUSH_CONSISTENT_VERSIONS",
276
  TIP_RUSH_GENERATE_CHANGELOG = "TIP_RUSH_GENERATE_CHANGELOG"
277
}
278

279
/**
280
 * Tip severity levels
281
 */
282
enum CustomTipSeverity {
283
  warning = "warning",
284
  suggestion = "suggestion"
285
}
286

287
/**
288
 * Tip types
289
 */
290
enum CustomTipType {
291
  machineReadable = "machineReadable",
292
  humanReadable = "humanReadable"
293
}
294
```
295

296
### Environment Configuration
297

298
Management of environment variables and Rush runtime environment settings.
299

300
```typescript { .api }
301
/**
302
 * Manages environment variables for Rush operations
303
 */
304
class EnvironmentConfiguration {
305
  /** Environment variables map */
306
  readonly environmentVariables: ReadonlyMap<string, string>;
307
  
308
  /** Load configuration from file */
309
  static loadFromFile(jsonFilename: string): EnvironmentConfiguration;
310
  
311
  /** Get environment variable value */
312
  getEnvironmentVariable(name: string): string | undefined;
313
  
314
  /** Set environment variable */
315
  setEnvironmentVariable(name: string, value: string): void;
316
  
317
  /** Apply environment variables to process */
318
  applyToProcess(): void;
319
}
320

321
/**
322
 * Standard Rush environment variable names
323
 */
324
enum EnvironmentVariableNames {
325
  RUSH_INVOKED_FOLDER = "RUSH_INVOKED_FOLDER",
326
  RUSH_TEMP_FOLDER = "RUSH_TEMP_FOLDER",
327
  _RUSH_LIB_PATH = "_RUSH_LIB_PATH"
328
}
329
```
330

331
**Usage Examples:**
332

333
```typescript
334
import { EnvironmentConfiguration, EnvironmentVariableNames } from "@rushstack/rush-sdk";
335

336
const envConfig = EnvironmentConfiguration.loadFromFile(
337
  path.join(config.commonRushConfigFolder, "environment.json")
338
);
339

340
// Check specific environment variables
341
const rushPath = envConfig.getEnvironmentVariable(EnvironmentVariableNames._RUSH_LIB_PATH);
342
if (rushPath) {
343
  console.log(`Rush lib path: ${rushPath}`);
344
}
345

346
// Set new environment variable
347
envConfig.setEnvironmentVariable("MY_CUSTOM_VAR", "custom-value");
348

349
// Apply to current process
350
envConfig.applyToProcess();
351

352
// List all configured variables
353
for (const [name, value] of envConfig.environmentVariables) {
354
  console.log(`${name}=${value}`);
355
}
356
```
357

358
### Repository State Management
359

360
Management of repository state files and persistent workspace information.
361

362
```typescript { .api }
363
/**
364
 * Manages repository state information
365
 */
366
class RepoStateFile {
367
  /** Path to repo state file */
368
  readonly filePath: string;
369
  
370
  /** Last update time */
371
  readonly lastUpdateTime: Date;
372
  
373
  /** Pnpm shrinkwrap hash */
374
  readonly pnpmShrinkwrapHash?: string;
375
  
376
  /** Load from file */
377
  static loadFromFile(filePath: string): RepoStateFile;
378
  
379
  /** Check if file exists */
380
  static exists(filePath: string): boolean;
381
  
382
  /** Update pnpm shrinkwrap hash */
383
  updatePnpmShrinkwrapHash(hash: string): void;
384
  
385
  /** Save state to file */
386
  save(): void;
387
  
388
  /** Delete state file */
389
  delete(): void;
390
}
391
```