Skip to content

Commit e51f576

Browse files
Copiloticlanton
andcommitted
Improve Rush plugin authoring documentation
- Remove stale "(experimental)" labels from plugin page titles - Add lifecycle hooks reference table to creating_plugins.md - Add service registration API documentation (build cache, cobuild) - Add code example for tapping specific phased commands - Update first-party plugins table with 4 missing plugins: rush-bridge-cache-plugin, rush-http-build-cache-plugin, rush-redis-cobuild-plugin, rush-resolver-cache-plugin Co-authored-by: iclanton <5010588+iclanton@users.noreply.github.com>
1 parent 8689f86 commit e51f576

3 files changed

Lines changed: 53 additions & 4 deletions

File tree

websites/rushjs.io/docs/pages/configs/rush-plugin-manifest_json.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: rush-plugin-manifest.json (experimental)
2+
title: rush-plugin-manifest.json
33
---
44

55
This is the template for the **rush-plugin-manifest.json** file that is used when

websites/rushjs.io/docs/pages/extensibility/creating_plugins.md

Lines changed: 46 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: Creating Rush plugins (experimental)
2+
title: Creating Rush plugins
33
---
44

55
Rush plugins enable repository maintainers to:
@@ -136,6 +136,51 @@ Example project for this scenario:
136136
> use the `"associatedCommands"` setting to improve performance by
137137
> avoiding loading the module when it is not needed.
138138
139+
### Available lifecycle hooks
140+
141+
The [RushSession.hooks](https://api.rushstack.io/pages/rush-lib.rushsession/) object exposes
142+
[lifecycle hooks](https://api.rushstack.io/pages/rush-lib.rushlifecyclehooks/) that your plugin can
143+
use to register its handlers. The hook system is based on the
144+
[tapable](https://www.npmjs.com/package/tapable) framework familiar from Webpack.
145+
146+
| Hook | Type | Description |
147+
| :--- | :--- | :---------- |
148+
| `initialize` | `AsyncSeriesHook` | Called before executing any Rush CLI command. |
149+
| `runAnyGlobalCustomCommand` | `AsyncSeriesHook` | Called before executing any global custom command (defined in command-line.json). |
150+
| `runGlobalCustomCommand` | `HookMap` | A hook map to target specific named global commands before execution. |
151+
| `runAnyPhasedCommand` | `AsyncSeriesHook` | Called before executing any phased command (including the default `build` and `rebuild`). |
152+
| `runPhasedCommand` | `HookMap` | A hook map to target specific named phased commands before execution. |
153+
| `beforeInstall` | `AsyncSeriesHook` | Called between preparing the common/temp folder and invoking the package manager during `rush install` or `rush update`. |
154+
| `afterInstall` | `AsyncSeriesHook` | Called after a successful install. |
155+
| `flushTelemetry` | `AsyncParallelHook` | Allows plugins to process telemetry data. |
156+
157+
For example, to tap a specific phased command:
158+
159+
```ts
160+
public apply(rushSession: RushSession, rushConfiguration: RushConfiguration): void {
161+
rushSession.hooks.runPhasedCommand.for('build').tapPromise(
162+
this.pluginName,
163+
async (command: IPhasedCommand) => {
164+
const logger: ILogger = rushSession.getLogger(this.pluginName);
165+
logger.terminal.writeLine('The "rush build" command is about to run!');
166+
}
167+
);
168+
}
169+
```
170+
171+
### Registering service providers
172+
173+
The `RushSession` object also provides methods for plugins that implement build cache or cobuild
174+
lock providers:
175+
176+
| Method | Description |
177+
| :----- | :---------- |
178+
| `registerCloudBuildCacheProviderFactory(name, factory)` | Registers a factory that creates a cloud build cache provider for the given provider name. |
179+
| `registerCobuildLockProviderFactory(name, factory)` | Registers a factory that creates a cobuild lock provider for the given provider name. |
180+
181+
These are used by plugins such as `@rushstack/rush-amazon-s3-build-cache-plugin` and
182+
`@rushstack/rush-redis-cobuild-plugin` to integrate with Rush's build cache and cobuild systems.
183+
139184
### Defining a config file for your plugin
140185

141186
Often a plugin will need to be configured using its own custom settings. Rush's convention

websites/rushjs.io/docs/pages/maintainer/using_rush_plugins.md

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: Using Rush plugins (experimental)
2+
title: Using Rush plugins
33
---
44

55
Rush plugins enable you to:
@@ -110,7 +110,11 @@ The config filename will have the same as the `pluginName`, for example:
110110
| :------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------- |
111111
| [@rushstack/rush-amazon-s3-build-cache-plugin](https://github.com/microsoft/rushstack/tree/main/rush-plugins/rush-amazon-s3-build-cache-plugin) | Cloud build cache provider for Amazon S3 |
112112
| [@rushstack/rush-azure-storage-build-cache-plugin](https://github.com/microsoft/rushstack/tree/main/rush-plugins/rush-azure-storage-build-cache-plugin) | Cloud build cache provider for Azure Storage |
113-
| [@rushstack/rush-serve-plugin](https://github.com/microsoft/rushstack/tree/main/rush-plugins/rush-serve-plugin) | (Experimental) A Rush plugin that hooks into action execution and runs an express server to serve project outputs |
113+
| [@rushstack/rush-bridge-cache-plugin](https://github.com/microsoft/rushstack/tree/main/rush-plugins/rush-bridge-cache-plugin) | Bypasses command execution to populate or restore the build cache from an external orchestrator |
114+
| [@rushstack/rush-http-build-cache-plugin](https://github.com/microsoft/rushstack/tree/main/rush-plugins/rush-http-build-cache-plugin) | Cloud build cache provider using a generic HTTP endpoint |
115+
| [@rushstack/rush-redis-cobuild-plugin](https://github.com/microsoft/rushstack/tree/main/rush-plugins/rush-redis-cobuild-plugin) | Cobuild lock provider using Redis for distributed builds |
116+
| [@rushstack/rush-resolver-cache-plugin](https://github.com/microsoft/rushstack/tree/main/rush-plugins/rush-resolver-cache-plugin) | Generates a resolver cache file to optimize Node.js module resolution |
117+
| [@rushstack/rush-serve-plugin](https://github.com/microsoft/rushstack/tree/main/rush-plugins/rush-serve-plugin) | Hooks into action execution and runs an Express server to serve project outputs in watch mode |
114118

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

0 commit comments

Comments
 (0)