Rush StackShopBlogEvents
Skip to main content

Using Rush plugins (experimental)

Rush plugins enable you to:

  • Share common Rush configuration across multiple monorepos
  • Extend Rush's base functionality with custom features
  • Prototype new feature ideas before officially contributing them to Rush

Plugins are distributed via an NPM package, which we call a plugin package. A single package may define one or more Rush plugins. (If you are interested in creating your plugin package, see the article Creating rush plugins.)

Enabling a Rush plugin​

There are three steps for enabling a Rush plugin in your monorepo. For this tutorial, let's configure a hypothetical plugin called "example" that is provided by the NPM package @your-company/rush-example-plugin.

Step 1: Configure an autoinstaller​

Plugins rely on Rush's autoinstaller feature for on-demand installation of their NPM package.

Here's how to create a new autoinstaller called rush-plugins:

rush init-autoinstaller --name rush-plugins

This will create an autoinstaller package.json file. Add your plugin's NPM package as a dependency:

common/autoinstallers/rush-plugins/package.json

{
  "name": "rush-plugins",
  "version": "1.0.0",
  "private": true,
  "dependencies": {
    "@your-company/rush-example-plugin": "^1.0.0"  👈 👈 👈
  }
}

Next, generate the shrinkwrap file:

# Creates the shrinkwrap file common/autoinstallers/rush-plugins/pnpm-lock.yaml
rush update-autoinstaller --name rush-plugins

Commit these files to Git.

Step 2: Update rush-plugins.json​

In order for the plugin to be loaded, we need to register it in rush-plugins.json. Continuing our example:

common/config/rush/rush-plugins.json

{
  "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/rush-plugins.schema.json",
  "plugins": [
    /**
     * Each item defines a plugin to be loaded by Rush.
     */
    {
      /**
       * The name of the NPM package that provides the plugin.
       */
      "packageName": "@your-company/rush-example-plugin",

      /**
       * The name of the plugin.  This can be found in the "pluginName"
       * field of the "rush-plugin-manifest.json" file in the NPM package folder.
       */
      "pluginName": "example",

      /**
       * The name of a Rush autoinstaller that will be used for installation, which
       * can be created using "rush init-autoinstaller".  Add the plugin's NPM package
       * to the package.json "dependencies" of your autoinstaller, then run
       * "rush update-autoinstaller".
       */
      "autoinstallerName": "rush-plugins"
    }
  ]
}

The pluginName field can be found in the rush-plugin-manifest.json of the plugin package.

Step 3: Optional config file​

Some plugins can be customized via their own config file; if so, their rush-plugin-manifest.json will specify the optionsSchema field.

The config filename will have the same as the pluginName, for example:

common/config/rush-plugins/example.json

First-party plugins​

NPM PackageDescription
@rushstack/rush-amazon-s3-build-cache-pluginCloud build cache provider for Amazon S3
@rushstack/rush-azure-storage-build-cache-pluginCloud build cache provider for Azure Storage
@rushstack/rush-serve-plugin(Experimental) A Rush plugin that hooks into action execution and runs an express server to serve project outputs

NOTE: The @rushstack/rush-amazon-s3-build-cache-plugin and @rushstack/rush-azure-storage-build-cache-plugin packages are currently built-in to Rush and enabled automatically. For now, you should NOT register them in rush-plugins.json.

This is a temporary accommodation while the plugin framework is still experimental. In the next major release of Rush, the build cache packages will need to be configured in standard way.

Third-party plugins​

Here's a gallery of some community contributed plugins.

NPM PackageDescription
rush-archive-project-pluginArchive Rush projects that are no longer maintained
rush-init-project-pluginInitialize new Rush projects
rush-lint-staged-pluginIntegrate lint-staged with a Rush monorepo
rush-print-log-if-error-pluginPrint a project's entire log file when an error occurs
rush-sort-package-jsonSort the package.json file entries for Rush projects
rush-upgrade-self-pluginA helper for upgrading to the latest release of Rush

If you created an interesting plugin for Rush, let us know in a GitHub issue. Thanks!

See also​