# @rushstack/rush-sdk

> An API for interacting with the Rush engine

Latest version **5.181.0** (published 2026-10-06) · MIT license · 0 weekly downloads

## Install

```sh
npm install @rushstack/rush-sdk
pnpm add @rushstack/rush-sdk
yarn add @rushstack/rush-sdk
bun add @rushstack/rush-sdk
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 5.181.0 |
| Published | 2026-10-06 |
| First published | 2021-11-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20.9.0 |
| Dependencies | 8 |
| Unpacked size | 1.2 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 6499 |
| Maintainers | rushstack-admin, odspnpm, octogonz, microsoft1es |

## Links

- npm: https://www.npmjs.com/package/@rushstack/rush-sdk
- Repository: https://github.com/microsoft/rushstack
- Homepage: https://rushjs.io
- Issues: https://github.com/microsoft/rushstack/issues
- npm.io page: https://npm.io/package/@rushstack/rush-sdk

## Dependencies (8)

- [tapable](https://npm.io/package/tapable.md) 2.2.1
- [@rushstack/terminal](https://npm.io/package/@rushstack/terminal.md) 0.24.7
- [@pnpm/lockfile.types-900](https://npm.io/package/@pnpm/lockfile.types-900.md) npm:@pnpm/lockfile.types@~900.0.0
- [@rushstack/rush-reporter](https://npm.io/package/@rushstack/rush-reporter.md) 0.4.1
- [@rushstack/lookup-by-path](https://npm.io/package/@rushstack/lookup-by-path.md) 0.10.19
- [@rushstack/credential-cache](https://npm.io/package/@rushstack/credential-cache.md) 0.2.30
- [@rushstack/node-core-library](https://npm.io/package/@rushstack/node-core-library.md) 5.25.1
- [@rushstack/package-deps-hash](https://npm.io/package/@rushstack/package-deps-hash.md) 4.8.0

## Recent versions

- 5.181.0 (latest) — 2026-10-06
- 5.170.1-pr5378.0 (pr5378) — 2026-03-21
- 5.165.0-pr5496.3 (pr5496) — 2026-01-12
- 5.165.0-pr5496.1 (pr5280) — 2025-12-30
- 5.158.1-pr5355.0 (pr5355) — 2025-09-25
- 5.145.0-pr5009.2 (pr5009) — 2024-12-10
- 5.144.1-pr5037.0 (pr5037) — 2024-12-10
- 5.144.0-pr5031.1 (pr5031) — 2024-12-09
- 5.138.0-pr4476.0 (pr4476) — 2024-10-04
- 5.135.0-pr4927.1 (pr4927) — 2024-09-22
- 5.109.1-pr3481.22 (pr3481) — 2024-02-19
- 5.112.2-pr4485.3 (pr4485) — 2024-02-08
- 5.102.0-pr3949.7 (pr3949) — 2023-08-30
- 5.100.0-pr4132.1 (pr4132) — 2023-06-08
- 5.90.2-pr3964.0 (pr3954) — 2023-02-18
- … 323 more at https://npm.io/package/@rushstack/rush-sdk/versions

## README

## @rushstack/rush-sdk

This is a companion package for the Rush tool. See the [@microsoft/rush](https://www.npmjs.com/package/@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:

1. **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.

2. **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 regular `dependencies`. In this context, **@rushstack/rush-sdk** will resolve to the locally installed instance for testing purposes.

3. **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.

4. **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.

5. **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:

```ts
// CommonJS notation:
const { RushConfiguration } = require('@rushstack/rush-sdk');

const config = RushConfiguration.loadFromDefaultLocation();
console.log(config.commonFolder);
```

```ts
// 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:

```ts
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:

```ts
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 from `rush-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:

```ts
// 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:

```ts
// 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](https://github.com/microsoft/rushstack/blob/main/apps/rush/CHANGELOG.md) - Find
  out what's new in the latest version
- [API Reference](https://api.rushstack.io/pages/rush-lib/)

Rush is part of the [Rush Stack](https://rushstack.io/) family of projects.

---
_Source: https://npm.io/package/@rushstack/rush-sdk · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._