@rushstack/rush-sdk
v5.141.1
Published
An API for interacting with the Rush engine
Downloads
1,426,025
Readme
@rushstack/rush-sdk
This is a companion package for the Rush tool. See the @microsoft/rush package for details.
⚠ THIS PACKAGE IS EXPERIMENTAL ⚠
The @rushstack/rush-sdk package acts as a lightweight proxy for accessing the APIs of the @microsoft/rush-lib engine. It is intended to support five different use cases:
Rush plugins: Rush plugins should import from @rushstack/rush-sdk instead of @microsoft/rush-lib. This gives plugins full access to Rush APIs while avoiding a redundant installation of those packages. At runtime, the APIs will be bound to the correct
rushVersion
from rush.json, and guaranteed to be the same @microsoft/rush-lib module instance as the plugin host.Unit tests: When authoring unit tests (for a Rush plugin, for example), developers should add @microsoft/rush-lib to their package.json
devDependencies
and add @rushstack/rush-sdk to the regulardependencies
. In this context, @rushstack/rush-sdk will resolve to the locally installed instance for testing purposes.Rush subprocesses: For tools within a monorepo that import @rushstack/rush-sdk during their build process, child processes will inherit the installation of Rush that invoked them. This is communicated using the
_RUSH_LIB_PATH
environment variable.Monorepo tools: For scripts and tools that are designed to be used in a Rush monorepo, @rushstack/rush-sdk will automatically invoke install-run-rush.js and load the local installation. This ensures that tools load a compatible version of the Rush engine for the given branch.
Advanced scenarios: The secondary
@rushstack/rush-sdk/loader
entry point can be imported by tools that need to explicitly control where @microsoft/rush-lib gets loaded from. This API also allows monitoring installation and canceling the operation. This API is used by the Rush Stack VS Code extension, for example.
The @rushstack/rush-sdk API declarations are identical to the corresponding version of @microsoft/rush-lib.
Basic usage
Here's an example of basic usage that works with cases 1-4 above:
// CommonJS notation:
const { RushConfiguration } = require('@rushstack/rush-sdk');
const config = RushConfiguration.loadFromDefaultLocation();
console.log(config.commonFolder);
// TypeScript notation:
import { RushConfiguration } from '@rushstack/rush-sdk';
const config = RushConfiguration.loadFromDefaultLocation();
console.log(config.commonFolder);
Loader API
Here's a basic example of how to manually load @rushstack/rush-sdk and monitor installation progress:
import { RushSdkLoader, ISdkCallbackEvent } from '@rushstack/rush-sdk/loader';
if (!RushSdkLoader.isLoaded) {
await RushSdkLoader.loadAsync({
// the search for rush.json starts here:
rushJsonSearchFolder: "path/to/my-repo/apps/my-app",
onNotifyEvent: (event: ISdkCallbackEvent) => {
if (event.logMessage) {
// Your tool can show progress about the loading:
if (event.logMessage.kind === 'info') {
console.log(event.logMessage.text);
}
}
}
});
}
// Any subsequent attempts to call require() will return the same instance
// that was loaded above.
const rushSdk = require('@rushstack/rush-sdk');
const config = rushSdk.RushConfiguration.loadFromDefaultLocation();
Here's a more elaborate example illustrating other API features:
import { RushSdkLoader, ISdkCallbackEvent } from '@rushstack/rush-sdk/loader';
// Use an AbortController to cancel the operation after a certain time period
const abortController = new AbortController();
setTimeout(() => {
abortController.abort();
}, 1000);
if (!RushSdkLoader.isLoaded) {
await RushSdkLoader.loadAsync({
// the search for rush.json starts here:
rushJsonSearchFolder: "path/to/my-repo/apps/my-app",
abortSignal: abortController.signal,
onNotifyEvent: (event: ISdkCallbackEvent) => {
if (event.logMessage) {
// Your tool can show progress about the loading:
if (event.logMessage.kind === 'info') {
console.log(event.logMessage.text);
}
}
if (event.progressPercent !== undefined) {
// If installation takes a long time, your tool can display a progress bar
displayYourProgressBar(event.progressPercent);
}
}
});
}
// Any subsequent attempts to call require() will return the same instance
// that was loaded above.
const rushSdk = require('@rushstack/rush-sdk');
const config = rushSdk.RushConfiguration.loadFromDefaultLocation();
Importing internal APIs
Backwards compatibility is only guaranteed for the APIs marked as @public
in the official rush-lib.d.ts
entry point.
However, sometimes it is expedient for a script to import internal modules from @microsoft/rush-lib
to access
unofficial APIs. This practice faces a technical challenge that @microsoft/rush-lib
is bundled using Webpack.
The @rushstack/rush-sdk
package provides stub files that import the corresponding internal module from the
Webpack bundle, via the @rushstack/webpack-deep-imports-plugin
mechanism.
WARNING: If the loaded
rush-lib
package has a different version fromrush-sdk
, there is no guarantee that the corresponding path will exist or have the same type signature. Access internal APIs at your own risk. If you find an internal API to be useful, we recommend that you create a GitHub issue proposing to make it public.
Example 1: Conventional import of a public API:
// THIS IS THE RECOMMENDED PRACTICE:
import { RushConfiguration } from '@rushstack/rush-sdk';
const config = RushConfiguration.loadFromDefaultLocation();
console.log(config.commonFolder);
Example 2: How to import an internal API:
// WARNING: INTERNAL APIS MAY CHANGE AT ANY TIME -- USE THIS AT YOUR OWN RISK:
// Important: Since we're calling an internal API, we need to use the unbundled .d.ts files
// instead of the normal .d.ts rollup, otherwise TypeScript will complain about a type mismatch.
import { RushConfiguration } from '@rushstack/rush-sdk/lib/index';
const config = RushConfiguration.loadFromDefaultLocation();
console.log(config.commonFolder);
// Load an internal module from the Webpack bundle using a path-based import of a stub file:
import { GitEmailPolicy } from '@rushstack/rush-sdk/lib/logic/policy/GitEmailPolicy';
console.log(GitEmailPolicy.getEmailExampleLines(config));
Debugging
Verbose logging can be enabled by setting environment variable RUSH_SDK_DEBUG=1
.
Links
- CHANGELOG.md - Find out what's new in the latest version
- API Reference
Rush is part of the Rush Stack family of projects.