or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

build-operations.mdconfiguration-files.mdconfiguration.mdindex.mdmanual-loading.mdpackage-management.mdversion-management.md
tile.json

tessl/npm-rushstack--rush-sdk

A lightweight proxy API for accessing @microsoft/rush-lib with smart loading and version resolution

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@rushstack/rush-sdk@5.158.x

To install, run

npx @tessl/cli install tessl/npm-rushstack--rush-sdk@5.158.0

index.mddocs/

Rush SDK

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.

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.

Package Information

  • Package Name: @rushstack/rush-sdk
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @rushstack/rush-sdk

Core Imports

import { RushConfiguration, Rush } from "@rushstack/rush-sdk";

For CommonJS:

const { RushConfiguration, Rush } = require("@rushstack/rush-sdk");

For loader API:

import { RushSdkLoader } from "@rushstack/rush-sdk/loader";

Basic Usage

import { RushConfiguration } from "@rushstack/rush-sdk";

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

// Access project information
for (const project of config.projects) {
  console.log(`${project.packageName} at ${project.projectRelativeFolder}`);
}

Architecture

Rush SDK is built around several key components:

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

Loading Scenarios

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

Capabilities

Rush SDK Core APIs

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

// All @microsoft/rush-lib exports are available through rush-sdk
export * from '@microsoft/rush-lib';

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

Key re-exported classes include:

class Rush {
  static readonly version: string;
  static ensureRushVersionIsCompatible(rushVersion: string): void;
}

class RushConstants {
  static readonly rushJsonFilename: string;
  static readonly rushLinkJsonFilename: string;
  static readonly commonFolderName: string;
  static readonly nodeModulesFolderName: string;
}

Rush Configuration Management

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

class RushConfiguration {
  static loadFromDefaultLocation(): RushConfiguration;
  static loadFromConfigurationFile(rushJsonFilename: string): RushConfiguration;
  static tryFindRushJsonLocation(startingFolder: string, options?: ITryFindRushJsonLocationOptions): string | undefined;
  readonly rushVersion: string;
  readonly projects: ReadonlyArray<RushConfigurationProject>;
  readonly projectsByName: ReadonlyMap<string, RushConfigurationProject>;
  readonly commonFolder: string;
  readonly rushJsonFolder: string;
  readonly packageManager: string;
  readonly packageManagerToolVersion: string;
}

class RushConfigurationProject {
  readonly packageName: string;
  readonly projectRelativeFolder: string;
  readonly projectFolder: string;
  readonly packageJson: IPackageJson;
  readonly shouldPublish: boolean;
  readonly reviewCategory: string;
  readonly localDependencies: ReadonlyArray<RushConfigurationProject>;
}

interface ITryFindRushJsonLocationOptions {
  showVerbose?: boolean;
}

Configuration Management

Package Management

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.

abstract class PackageManager {
  readonly name: PackageManagerName;
  readonly version: string;
}

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

class NpmOptionsConfiguration extends PackageManagerOptionsConfigurationBase {
  readonly environmentVariables: ReadonlyMap<string, string>;
}

class PnpmOptionsConfiguration extends PackageManagerOptionsConfigurationBase {
  readonly environmentVariables: ReadonlyMap<string, string>;
  readonly pnpmStorePath?: string;
  readonly resolutionMode?: PnpmResolutionMode;
}

class YarnOptionsConfiguration extends PackageManagerOptionsConfigurationBase {
  readonly environmentVariables: ReadonlyMap<string, string>;
}

abstract class PackageManagerOptionsConfigurationBase {
  readonly environmentVariables: ReadonlyMap<string, string>;
}

type PnpmResolutionMode = 'highest' | 'time-based' | 'lowest-direct';

Package Management

Build Operations and Change Detection

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

class Operation {
  readonly name: string;
  readonly status: OperationStatus;
  readonly dependencies: ReadonlySet<Operation>;
  executeAsync(): Promise<OperationStatus>;
}

enum OperationStatus {
  Executing = 'executing',
  Success = 'success',
  SuccessWithWarning = 'success:warning',
  Failure = 'failure',
  Blocked = 'blocked',
  Skipped = 'skipped'
}

class ChangeManager {
  static hasChanges(project: RushConfigurationProject): boolean;
}

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

interface IGetChangedProjectsOptions {
  targetBranchName?: string;
  enableFiltering?: boolean;
  verbose?: boolean;
}

Build Operations

Version Management

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

abstract class VersionPolicy {
  readonly policyName: string;
  readonly definitionName: VersionPolicyDefinitionName;
  abstract bump(bumpType?: BumpType): void;
}

class IndividualVersionPolicy extends VersionPolicy {
  readonly lockedMajor?: number;
}

class LockStepVersionPolicy extends VersionPolicy {
  readonly version: string;
  readonly nextBump?: BumpType;
}

enum BumpType {
  prerelease = 'prerelease',
  patch = 'patch',
  minor = 'minor',
  major = 'major'
}

enum VersionPolicyDefinitionName {
  lockStepVersion = 'lockStepVersion',
  individualVersion = 'individualVersion'
}

class VersionPolicyConfiguration {
  static loadFromFile(jsonFilename: string): VersionPolicyConfiguration;
  readonly versionPolicies: ReadonlyArray<VersionPolicy>;
}

Version Management

Manual Loading API

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.

class RushSdkLoader {
  static readonly isLoaded: boolean;
  static loadAsync(options?: ILoadSdkAsyncOptions): Promise<void>;
}

interface ILoadSdkAsyncOptions {
  rushJsonSearchFolder?: string;
  abortSignal?: AbortSignal;
  onNotifyEvent?: SdkNotifyEventCallback;
}

interface ISdkCallbackEvent {
  logMessage: IProgressBarCallbackLogMessage | undefined;
  progressPercent: number | undefined;
}

interface IProgressBarCallbackLogMessage {
  text: string;
  kind: 'info' | 'debug';
}

type SdkNotifyEventCallback = (sdkEvent: ISdkCallbackEvent) => void;

Manual Loading

Configuration Files Management

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

class CommonVersionsConfiguration {
  readonly filePath: string;
  readonly preferredVersions: ReadonlyMap<string, string>;
  save(): void;
}

class ApprovedPackagesConfiguration {
  readonly approvedPackages: ReadonlyArray<ApprovedPackagesItem>;
  addOrUpdatePackage(packageName: string, reviewCategory: string): ApprovedPackagesItem;
}

class ApprovedPackagesItem {
  readonly packageName: string;
  readonly allowedCategories: ReadonlySet<string>;
}

class ExperimentsConfiguration {
  readonly configuration: ReadonlyMap<string, boolean>;
  isFeatureEnabled(featureName: string): boolean;
}

Configuration Files

Internal API Access

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

function _rushSdk_loadInternalModule(srcImportPath: string): unknown;

Usage Examples:

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

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

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

// Path-based import of internal API using stub files
import { GitEmailPolicy } from "@rushstack/rush-sdk/lib/logic/policy/GitEmailPolicy";
console.log(GitEmailPolicy.getEmailExampleLines(config));

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

Types

// Core types re-exported from @microsoft/rush-lib
interface IPackageJson {
  name: string;
  version: string;
  dependencies?: Record<string, string>;
  devDependencies?: Record<string, string>;
  peerDependencies?: Record<string, string>;
  optionalDependencies?: Record<string, string>;
}

enum DependencyType {
  Regular = 'dependencies',
  Dev = 'devDependencies',
  Optional = 'optionalDependencies',
  Peer = 'peerDependencies'
}

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

interface IProgressBarCallbackLogMessage {
  text: string;
  kind: 'info' | 'debug';
}

interface ILaunchOptions {
  isManaged?: boolean;
  alreadyReportedNodeTooNewError?: boolean;
}

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

interface IRushSessionOptions {
  terminalProvider?: ITerminalProvider;
  getIsDebugMode?: () => boolean;
}