|
1 | 1 | --- |
2 | | -title: Creating Rush plugins (experimental) |
| 2 | +title: Creating Rush plugins |
3 | 3 | --- |
4 | 4 |
|
5 | 5 | Rush plugins enable repository maintainers to: |
@@ -136,6 +136,51 @@ Example project for this scenario: |
136 | 136 | > use the `"associatedCommands"` setting to improve performance by |
137 | 137 | > avoiding loading the module when it is not needed. |
138 | 138 |
|
| 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 | + |
139 | 184 | ### Defining a config file for your plugin |
140 | 185 |
|
141 | 186 | Often a plugin will need to be configured using its own custom settings. Rush's convention |
|
0 commit comments