Rush Stack商店部落格活動
跳至主要內容

建立 Rush 外掛程式 (實驗性質)

Rush 外掛程式讓儲存庫維護人員能夠

  • 在多個單一儲存庫之間共用常見的 Rush 設定
  • 使用自訂功能擴充 Rush 的基本功能
  • 在正式將新功能構想貢獻給 Rush 之前，先進行原型設計

建立外掛程式套件​

外掛程式套件是一個提供一或多個 Rush 外掛程式的 NPM 套件。這些外掛程式由外掛程式資訊清單檔案描述。這個檔案一律命名為 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
    }
  ]
}

此案例的範例專案：來自 bytesfriends 的 rush-sort-package-json

載入程式碼模組​

外掛程式可以使用 @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 會公開各種 生命週期 Hook，您的外掛程式可以使用這些 Hook 來註冊其處理常式。Hook 系統是根據 Webpack 中常用的 tapable 框架。

此案例的範例專案：@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",
    . . .

另請參閱​