Run script plugin

Plugin package:	@rushstack/heft (built-in)
Plugin name:	run-script-plugin implemented by RunScriptPlugin.ts
Plugin config file:	(none)
heft.json options:	run-script-options.schema.json

This plugin allows a Heft task to execute an arbitrary JavaScript file which can perform similar actions as a Heft task plugin.

When to use it

This plugin is generally NOT recommended. If you need to perform custom operations during a Heft build, the best practice is to create a proper Heft plugin package. Doing so ensures that your code is professionally developed with TypeScript and ESLint validation, and therefore easier to maintain. The run-script-plugin should only be used for experimentation or small bits of code to solve one-off problems.

package.json dependencies

None - this feature is built-in to @rushstack/heft.

Configuration

The run-script-plugin is a built-in plugin loaded directly from @rushstack/heft. Here's a code sample for a task that loads this plugin:

<project folder>/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"
            }
            // --------------------------------------------------------------
          }
        }
      }
    }
  }
}

The "scriptPath" should refer to a Node.js module that will be loaded using await import(scriptPath), resolved relative to the project folder. The script should export a function named runAsync() that will be invoked when the task is run. The function receives a single options parameter with this type:

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 `cancellationToken` 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>;
}

Here is a sample implementation of the runAsync() function:

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.cancellationToken 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.cancellationToken so that Heft can gracefully abort the operation.
    options.heftTaskSession.logger.terminal.writeLine('Hello, world!');
  }
};

heft.json plugin options

This commented template documents the available options. In the above example, it would get pasted between the ------ bars.

// 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"
  // }
}