Rush Stack商店博客活动
跳至主要内容

创建 Rush 插件（实验性）

Rush 插件使仓库维护者能够

  • 在多个单体仓库之间共享通用的 Rush 配置
  • 使用自定义功能扩展 Rush 的基本功能
  • 在正式贡献到 Rush 之前对新功能想法进行原型设计

创建插件包​

一个 **插件包** 是一个 NPM 包，它提供了一个或多个 **Rush 插件**。插件由 **插件清单** 文件描述。此文件始终命名为 rush-plugin-manifest.json，位于与 **package.json** 文件相同的文件夹中。

常见的可扩展性场景​

定义 Rush 自定义命令​

插件可以使用与实现 Rush 自定义命令 所用相同的 **command-line.json** 文件格式来定义扩展 Rush 命令行的新的命令和参数。

这是一个示例

rush-example-plugin/rush-plugin-manifest.json

{
  "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/rush-plugin-manifest.schema.json",
  "plugins": [
    {
      "pluginName": "check-readme",

      "description": "Adds a custom command \"rush check-readme\" that validates each project's README.md",

      /**
       * (Optional) A path to a "command-line.json" file that defines Rush command line actions
       * and parameters contributed by this plugin.  This config file has the same JSON schema
       * as Rush's "common/config/rush/command-line.json" file.
       */
      "commandLineJsonFilePath": "./command-line.json"
    }
  ]
}

rush-example-plugin/command-line.json

{
  "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/command-line.schema.json",
  "commands": [
    {
      "name": "check-readme",
      "commandKind": "bulk",
      "summary": "Validates a project's README.md to make sure it conforms to company policy",
      "shellCommand": "node <packageFolder>/lib/start.js",
      "safeForSimultaneousRushProcesses": true
    }
  ]
}

此场景的示例项目：rush-sort-package-json 来自 **bytesfriends**

加载代码模块​

插件可以使用 @rushstack/rush-sdk API 来注册 Rush 事件和服务的处理程序。这在插件清单中使用 entryPoint 设置来指定。

rush-example-plugin/rush-plugin-manifest.json

{
  "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/rush-plugin-manifest.schema.json",
  "plugins": [
    {
      "pluginName": "check-readme",
      "description": "Adds a custom command \"rush check-readme\" that validates each project's README.md",

      /**
       * (Optional) A path to a JavaScript code module that implements the "IRushPlugin" interface.
       * This module can use the "@rushstack/rush-sdk" API to register handlers for Rush events
       * and services.  The module path is relative to the folder containing the "package.json" file.
       */
      "entryPoint": "lib/RushExamplePlugin.js"
    }
  ]
}

插件模块应该有一个 default 导出，它是 IRushPlugin 接口的实现。

例如

rush-example-plugin/src/RushExamplePlugin.ts

import type { IRushPlugin, RushSession, RushConfiguration } from '@rushstack/rush-sdk';

export interface IRushExamplePluginOptions {}

export class RushExamplePlugin implements IRushPlugin {
  public readonly pluginName: string = 'RushExamplePlugin';

  public constructor(options: IRushExamplePluginOptions) {
    // Add your initialization here
  }

  public apply(rushSession: RushSession, rushConfiguration: RushConfiguration): void {
    rushSession.hooks.initialize.tap(this.pluginName, () => {
      const logger: ILogger = rushSession.getLogger(this.pluginName);
      logger.terminal.writeLine('Add your custom logic here');
    });
  }
}

export default { RushExamplePlugin };

RushSession.hooks API 公开了各种 生命周期钩子，你的插件可以使用这些钩子来注册其处理程序。钩子系统基于流行的 tapable 框架，该框架在 Webpack 中很熟悉。

此场景的示例项目：@rushstack/rush-amazon-s3-build-cache-plugin

**注意：**如果你的代码模块仅在某些 Rush 命令中使用，请使用 "associatedCommands" 设置来提高性能，方法是在不需要时避免加载模块。

为你的插件定义配置文件​

插件通常需要使用其自己的自定义设置进行配置。Rush 的约定是，插件的配置文件应存储在 **common/config/rush-plugins** 文件夹中，其文件名与清单中的 "pluginName" 字段相同。

这是一个完整的示例，演示了此命名模式

插件组件示例命名模式
NPM 包名称@your-company/rush-policy-plugins
rush-plugin-manifest.json 中的 "pluginName""email-policy"
最终用户配置文件<仓库>/common/config/rush-plugins/email-policy.json
配置文件 JSON 模式src/schemas/email-policy.schema.json
代码模块src/RushEmailPolicyPlugin.ts

要启用 Rush 对你的插件配置文件的自动验证，请在你的插件清单中指定 optionsSchema 设置

rush-policy-plugins/rush-plugin-manifest.json

    . . .
    /**
     * (Optional) A path to a JSON schema for validating the config file that end users can
     * create to customize this plugin's behavior.  Plugin config files are stored in the folder
     * "common/config/rush-plugins/" with a filename corresponding to the "pluginName" field
     * from the manifest.  For example: "common/config/rush-plugins/business-policy.json"
     * whose schema is "business-policy.schema.json".
     */
    "optionsSchema": "lib/schemas/email-policy.schema.json",
    . . .

另请参阅​