npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@rushstack/rush-sdk

v5.147.0

Published

An API for interacting with the Rush engine

Downloads

1,249,050

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:

  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:

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

// 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

Rush is part of the Rush Stack family of projects.