运行脚本插件

插件包	@rushstack/heft (内置)
插件名称	run-script-plugin 由 RunScriptPlugin.ts 实现
插件配置文件	(无)
heft.json 选项	run-script-options.schema.json

此插件允许 Heft 任务执行任意 JavaScript 文件，该文件可以执行与 Heft 任务插件类似的操作。

何时使用它

通常不建议使用此插件。如果您需要在 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" 应该引用一个 Node.js 模块，该模块将使用 await import(scriptPath) 加载，相对于项目文件夹解析。该脚本应该导出一个名为 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"
  // }
}