執行腳本外掛

外掛套件	@rushstack/heft (內建)
外掛名稱	run-script-plugin 由 RunScriptPlugin.ts 實作
外掛設定檔	(無)
heft.json 選項	run-script-options.schema.json

此外掛允許 Heft 工作執行可執行類似於 Heft 工作外掛動作的任意 JavaScript 檔案。

何時使用

一般不建議使用此外掛。如果您需要在 Heft 建置期間執行自訂操作，最佳做法就是建立適當的 Heft 外掛套件。這麼做可確保您的程式碼採用 TypeScript 和 ESLint 驗證專業開發，因此更容易維護。run-script-plugin 應只用於實驗或小段程式碼來解決一次性問題。

package.json 相依性

無 - 此功能內建於 @rushstack/heft。

組態

run-script-plugin 是從 @rushstack/heft 直接載入的內建外掛。以下是載入此外掛的工作範例程式碼

<專案資料夾>/config/heft.json

{
  "$schema": "https://developer.microsoft.com/json-schemas/heft/v0/heft.schema.json",
  "extends": "@rushstack/heft-web-rig/profiles/library/config/heft.json",

  "phasesByName": {
    // ("build" is a user-defined name, not a schema field)
    "build": {
      "tasksByName": {
        // ("post-compile" is a user-defined name, not a schema field)
        "post-compile": {
          // The "post-compile" task should not run until after "typescript" completes
          "taskDependencies": ["typescript"],

          "taskPlugin": {
            "pluginName": "run-script-plugin",
            "pluginPackage": "@rushstack/heft",

            // --------------------------------------------------------------
            // EXAMPLE OPTIONS FOR run-script-plugin
            "options": {
              "scriptPath": "lib/scripts/generate-version-file.js"
            }
            // --------------------------------------------------------------
          }
        }
      }
    }
  }
}

"scriptPath" 應參照將使用 await import(scriptPath) 載入的 Node.js 模組，相對於專案資料夾解析。指令碼應匯出名為 runAsync() 的函式，當執行作業時會呼叫該函式。函式會收到具有下列類型的單一 options 參數

export interface IRunScriptOptions {
  /**
   * The Heft session context, the same as for heft plugins.
   */
  heftTaskSession: IHeftTaskSession;

  /**
   * The Heft configuration.
   */
  heftConfiguration: HeftConfiguration;

  /**
   * If your script performs a long-running task, it must periodically check
   * this `abortSignal` so that Heft can gracefully abort the operation.
   */
  runOptions: IHeftTaskRunHookOptions;

  /**
   * The user-defined `scriptOptions` that can optionally be specified in **heft.json**.
   */
  scriptOptions: Record<string, unknown>;
}

以下是 runAsync() 函式的範例實作

TypeScript

import type { IRunScriptOptions } from '@rushstack/heft';

export async function runAsync(options: IRunScriptOptions): Promise<void> {
  // If your script performs a long-running task, it must periodically check
  // options.runOptions.abortSignal so that Heft can gracefully abort the operation.
  options.heftTaskSession.logger.terminal.writeLine('Hello, world!');
}

JavaScript

module.exports = {
  runAsync: async (options) => {
    // If your script performs a long-running task, it must periodically check
    // options.runOptions.abortSignal so that Heft can gracefully abort the operation.
    options.heftTaskSession.logger.terminal.writeLine('Hello, world!');
  }
};

heft.json 外掛選項

此註解範本記載可用的選項。在上述範例中，它會貼在 ------ 欄位之間。

// EXAMPLE OPTIONS FOR run-script-plugin
// JSON Schema: https://developer.microsoft.com/json-schemas/heft/v0/run-script-options.schema.json
"options": {

  /**
   * (REQUIRED) Path to the script that will be run, relative to the project root.
   */
  "scriptPath": "path/to/your/script",

  /**
   * User-defined JSON values that will be passed to the script at runtime.
   */
  // "scriptOptions": {
  //   "option1": "value"
  // }
}