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
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 init-autoinstaller --name rush-plugins
This will create an autoinstaller package.json file. Add your plugin's NPM package as a dependency:
"@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:
* Each item defines a plugin to be loaded by Rush.
* The name of the NPM package that provides the 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.
* 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".
pluginName field can be found in the
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
The config filename will have the same as the
pluginName, for example:
|@rushstack/rush-amazon-s3-build-cache-plugin||Cloud build cache provider for Amazon S3|
|@rushstack/rush-azure-storage-build-cache-plugin||Cloud 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|
@rushstack/rush-azure-storage-build-cache-pluginpackages 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.
Here's a gallery of some community contributed plugins.
|rush-archive-project-plugin||Archive Rush projects that are no longer maintained|
|rush-init-project-plugin||Initialize new Rush projects|
|rush-lint-staged-plugin||Integrate lint-staged with a Rush monorepo|
|rush-print-log-if-error-plugin||Print a project's entire log file when an error occurs|
|rush-sort-package-json||Sort the package.json file entries for Rush projects|
|rush-upgrade-self-plugin||A 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!