For a deeper dive into the multi-phase design and its underlying motivation, please see our other post What's New in Heft 0.51.

Version timeline​

Although most of the breaking changes are in Heft 0.51.0, other significant changes were made in several subsequent versions:

• Heft 0.51.0: The big architecture change for multi-phase support, with breaking changes for config file schemas and plugin APIs
• Heft 0.52.0: Restored support for the heft start alias (which had been removed in 0.51.0); added the ability to define custom aliases; @rushstack/heft-node-rig now launches its dev server using the same heft start alias as @rushstack/heft-web-rig
• Heft 0.53.0: Removed the taskEvents config setting; built-in tasks like copy-files-plugin and node-service-plugin now use identical configuration as third-party plugins (simply specifying @rushstack/heft as their plugin package name)
• Heft 0.54.0: Restored support for short parameter names such as -u in heft test -u (which had been removed in 0.51.0)
• Heft 0.55.0: Removed cacheFolderPath from plugin API's session object, since the .cache folder is no longer used

To simplify these migration notes, in this article we'll assume you're upgrading to 0.55.0 or newer, and that you're coming from 0.50.x or older.

Migrating heft.json files​

JSON Schema URL changes​

In order to have correct VS Code IntelliSense when editing config files, update the "$schema" field in each Heft config file. Simply replace json-schemas/heft/ with json-schemas/heft/v0.

For example:

• Old: "$schema": "https://developer.microsoft.com/json-schemas/heft/heft.schema.json"
• New: "$schema": "https://developer.microsoft.com/json-schemas/heft/v0/heft.schema.json"

The full list of JSON schema names can be found in this GitHub folder. These names are the last part of the URL shown above.

Plugins must be explicitly loaded​

In the old design, a number of plugins were built-in to @rushstack/heft and did not need to be explicitly loaded using heft.json settings. If their associated config file was not found, then their task would be silently skipped.

OLD: Plugins that were implicitly loaded:

• heft-typescript-plugin
• copy-static-assets-plugin
• copy-files-plugin
• delete-globs-plugin
• run-script-plugin
• api-extractor-plugin
• project-validator-plugin
• node-service-plugin

NEW: After migrating, every plugin must be explicitly loaded via the heft.json config file. Typically this is inherited from your rig. This new model eliminates magic and mysteries, since the full set of plugins and their dependencies is now represented in the config file.

If you are using our @rushstack/heft-node-rig and @rushstack/heft-web-rig, your project should only need minor changes, since the updated rigs now explicitly load all these plugins. If you created a custom rig, the migration work will be more involved, but you can copy from our examples:

• heft-node-rig/profiles/default/config/heft.json
• heft-web-rig/profiles/app/config/heft.json

Migrating package.json dependencies​

Many of these plugins have been extracted into their own NPM packages. This reduces the startup time and installation footprint for projects that don't use certain plugins.

Here's the current inventory as of this writing:

• @rushstack/heft: Its heft-plugin.json defines multiple plugins copy-files-plugin, delete-files-plugin, node-service-plugin, run-script-plugin
• @rushstack/heft-api-extractor-plugin
• @rushstack/heft-dev-cert-plugin
• @rushstack/heft-jest-plugin
• @rushstack/heft-lint-plugin
• @rushstack/heft-sass-plugin
• @rushstack/heft-serverless-stack-plugin
• @rushstack/heft-storybook-plugin
• @rushstack/heft-typescript-plugin
• @rushstack/heft-webpack4-plugin
• @rushstack/heft-webpack5-plugin

Migrating a standalone heft.json​

The old heft.json distinguished "event actions" (i.e. built-in tasks) versus "heftPlugins" (i.e. tasks from plugin packages).

OLD: heft.json excerpt from heft-node-rig

// ⚠️ OLD FORMAT EXAMPLE -- DO NOT USE! ⚠️
{
  "$schema": "https://developer.microsoft.com/json-schemas/heft/heft.schema.json",

  // "deleteGlobs" is specified to run with the "clean" event
  "eventActions": [
    {
      // 📌 [1] old way of cleaning
      "actionKind": "deleteGlobs",
      "heftEvent": "clean",
      "actionId": "defaultClean",
      "globsToDelete": ["dist", "lib", "lib-commonjs", "temp"]
    }
  ],

  // the Jest plugin is loaded using the "heftPlugins" section
  // and its event sequence was defined using program logic
  "heftPlugins": [
    // 📌 [2] old way of loading a plugin
    { "plugin": "@rushstack/heft-jest-plugin" }
  ]
}

NEW: heft.json excerpt from heft-node-rig

{
  "$schema": "https://developer.microsoft.com/json-schemas/heft/v0/heft.schema.json",

  "phasesByName": {
    // ("build" is a user-defined name, not a schema field)
    "build": {
      // 📌 [1] new way of cleaning
      "cleanFiles": [
        { "sourcePath": "dist" },
        { "sourcePath": "lib" },
        { "sourcePath": "lib-commonjs" }
      ],
      "tasksByName": {
        // ("typescript" is a user-defined name, not a schema field)
        "typescript": {
          "taskPlugin": {
            "pluginPackage": "@rushstack/heft-typescript-plugin"
          }
        },
        "lint": {
          "taskDependencies": ["typescript"],
          "taskPlugin": {
            "pluginPackage": "@rushstack/heft-lint-plugin"
          }
        },
        "api-extractor": {
          "taskDependencies": ["typescript"],
          "taskPlugin": {
            "pluginPackage": "@rushstack/heft-api-extractor-plugin"
          }
        },
        "node-service": {
          "taskDependencies": ["typescript"],
          "taskPlugin": {
            // This built-in plugin specifies "@rushstack/heft" as its package name
            "pluginPackage": "@rushstack/heft",
            "pluginName": "node-service-plugin"
          }
        }
      }
    },

    // ("test" is a user-defined name, not a schema field)
    "test": {
      "phaseDependencies": ["build"],
      "tasksByName": {
        // ("jest" is a user-defined name for this task)
        "jest": {
          // 📌 [2] new way of loading a plugin
          "taskPlugin": {
            "pluginPackage": "@rushstack/heft-jest-plugin"
          }
        }
      }
    }
  }
}

Looking at the above example, the major changes are:

• every task must be explicitly loaded from a pluginPackage, so the rig's heft.json is now more verbose (but more understandable!)
• built-in tasks (e.g. node-service) have identical specification as external plugins
• the old "heftEvent" lifecycle has been replaced by phaseDependencies and taskDependencies whose dependency graph determines the sequencing of tasks

The complete config file can be found here: heft-node-rig/profiles/default/config/heft.json

Migrating a rigged heft.json​

Here's another example from the TSDoc Playground project, whose heft.json inherits from our heft-web-rig:

OLD: heft.json excerpt from playground/config/heft.json

// ⚠️ OLD FORMAT EXAMPLE -- DO NOT USE! ⚠️
{
  "$schema": "https://developer.microsoft.com/json-schemas/heft/heft.schema.json",

  "extends": "@rushstack/heft-web-rig/profiles/library/config/heft.json",

  "eventActions": [
    {
      "actionId": "copyLicenseToDistFolder",
      "actionKind": "copyFiles",
      // 📌 [3] old way to do a post-compile action
      "heftEvent": "compile",
      "copyOperations": [
        {
          "destinationFolders": ["./dist"],
          // 📌 [4] old way of specifying a source folder
          "sourceFolder": "..",
          "includeGlobs": ["LICENSE"]
        }
      ]
    }
  ]
}

NEW: heft.json excerpt from playground/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-copy" is a user-defined name, not a schema field)
        "post-compile-copy": {
          // 📌 [3] new way to do a post-compile action, by depending on the relevant task(s)

          // The "post-compile-copy" task should not run until after "typescript" completes
          "taskDependencies": ["typescript"],

          "taskPlugin": {
            "pluginName": "copy-files-plugin",
            "pluginPackage": "@rushstack/heft",
            "options": {
              "copyOperations": [
                {
                  // 📌 [4] new way of specifying a source folder (or file path)
                  "sourcePath": "..",
                  "destinationFolders": ["./dist"],
                  "includeGlobs": ["LICENSE"]
                }
              ]
            }
          }
        }
      }
    }
  }
}

Observations:

• The changes here are minimal, since the rig provides most of the build definition
• The latest heft-web-rig uses heft-webpack5-plugin, so we had to upgrade from Webpack 4 -> 5 as part of this conversion
• The "heftEvent": "compile" event no longer exists; instead it must be represented via an equivalent "taskDependencies" entry, which references the rig's "typescript" task definition

Migrating a "pre-compile" action​

In the above example, we migrated our config file by replacing "heftEvent": "compile" with "taskDependencies": ["typescript"], which accomplishes the same thing by expressing that the action cannot be performed until after the "typescript" task has completed. But the "taskDependencies" is a unidirectional relationship. In this new model, how can we represent an event such as pre-compile?

Consider this hypothetical example:

OLD: heft.json sample

// ⚠️ OLD FORMAT EXAMPLE -- DO NOT USE! ⚠️
{
  "$schema": "https://developer.microsoft.com/json-schemas/heft/heft.schema.json",

  "extends": "@rushstack/heft-web-rig/profiles/app/config/heft.json",

  "eventActions": [
    {
      "actionKind": "copyFiles",
      "actionId": "copyAssets",
      // 📌 [5] old way to do a "post-compile" action
      "heftEvent": "pre-compile",
      "copyOperations": [
        {
          "sourceFolder": "node_modules/some-library/dist",
          "destinationFolders": ["temp/typings"],
          "includeGlobs": ["*.d.ts"]
        }
      ]
    }
  ]
}

NEW: heft.json sample

{
  "$schema": "https://developer.microsoft.com/json-schemas/heft/v0/heft.schema.json",

  "extends": "@rushstack/heft-web-rig/profiles/app/config/heft.json",

  "phasesByName": {
    // ("build" is a user-defined name, not a schema field)
    "build": {
      "tasksByName": {
        // ("pre-compile-copy" is a user-defined name, not a schema field)
        "pre-compile-copy": {
          "taskPlugin": {
            "pluginPackage": "@rushstack/heft",
            "pluginName": "copy-files-plugin",
            "options": {
              "copyOperations": [
                {
                  "sourcePath": "node_modules/some-library/dist",
                  "destinationFolders": ["temp/typings"],
                  "includeGlobs": ["*.d.ts"]
                }
              ]
            }
          }
        },

        // ("typescript" is a user-defined name, that is originally defined in the rig)
        "typescript": {
          // 📌 [5] new way to do a "post-compile" action
          // The "typescript" task should not run until after "pre-compile-copy" completes.
          "taskDependencies": ["pre-compile-copy"]
        }
      }
    }
  }
}

For reference, @rushstack/heft-web-rig defines the "typescript" task as follows:

heft-web-rig/profiles/app/config/heft.json excerpt

  . . .
  "typescript": {
    "taskDependencies": ["sass"],
    "taskPlugin": {
      "pluginPackage": "@rushstack/heft-typescript-plugin"
    }
  },
  . . .

Observations:

• Recall that we implemented "post-compile-copy" by specifying taskDependencies for our own task ("taskDependencies": ["typescript"])
• By contrast, "pre-compile-copy" is implemented by amending the taskDependencies for the rig's "typescript" task ("taskDependencies": ["pre-compile-copy"])
• The rig already has "taskDependencies": ["sass"]. But we do NOT need to specify "taskDependencies": ["typescript", "sass"] because by default, Heft's config parser will merge arrays by appending rather than replacing entries
• This merge behavior is implemented by @rushstack/heft-config-file and can be customized using property inheritance directives

Migrating command line syntax​

The old --watch command line parameter has been removed. Instead, watch mode is enabled by appending -watch to the action name.

OLD:

heft build --watch --verbose

NEW:

heft build-watch --verbose

Command aliases​

In the old design, heft start was a special action for launching dev servers. In the new design, it is a command alias defined in heft.json. The new aliasing system allows you to define your own custom aliases to shorten common commands.

heft-web-rig/profiles/app/config/heft.json excerpt

  // Define "heft start" to be an alias for "heft build-watch --serve".
  "aliasesByName": {
    "start": {
      "actionName": "build-watch",
      "defaultParameters": ["--serve"]
    }
  },

The --serve CLI parameter is our standard convention for launching a localhost dev server. It is supported by both heft-webpack5-plugin and the built-in node-service-plugin.

@rushstack/heft-jest-plugin changes​

Heft does not follow the Jest convention of using ts-jest to naively translate .ts files to .js. Instead, the full Heft toolchain is invoked, avoiding duplicate transpilation and ensuring accurate invocation of all preprocessors. In the past, this was implemented by pointing your jest.config.json at the source code ("roots": ["<rootDir>/src"]) and relying on @rushstack/heft-jest-plugin/exports/jest-build-transform.js to return Heft's output .js files. However newer releases of Jest introduced a snapshotResolver setting, which allows Jest to process "<rootDir>/lib" directly and still be able to update inline snapshots. The latest Heft adopted this approach because it provides a better debugging experience.

How to migrate: If you're using the Rush Stack rigs or extending from @rushstack/heft-jest-plugin/includes/jest-shared.config.json, just delete emitFolderNameForTests from your typescript.json file.

For more customized setups, here's the full list of underlying changes:

• These plugin options have been removed from @rushstack/heft-jest-plugin: extensionForTests, folderNameForTests, folderNameForSnapshots
• The emitFolderNameForTests setting is removed from config/typescript.json
• In jest.config.json, fields such as roots, testMatch, collectCoverageFrom should now point to the CommonJS output folder (lib-commonjs or lib) instead of the src folder
• In jest.config.json, moduleFileExtensions should no longer include .ts or .tsx extensions
• In jest.config.json, jest-build-transform.js is replaced by "snapshotResolver": "@rushstack/heft-jest-plugin/exports/jest-source-map-snapshot-resolver.js"
• For web development, we've introduced heft-jest-plugin/includes/jest-web.config.json (for web projects that write their CommonJS to lib-commonjs) alongside the familiar jest-shared.config.json (for Node.js projects that write their CommonJS to lib).

For a real world example, this GitHub diff shows the recent changes to heft-jest-plugin/includes/jest-shared.config.json.

Migrating custom plugins​

In updating to the new version of Heft, plugins will also need to be updated for compatibility. Some of the more notable API changes include:

• The heft-plugin.json manifest file must accompany any plugin package. If no heft-plugin.json file is found, Heft will report an error.
• Plugin classes must have parameterless constructors, and must be the default export of the file pointed to by the entryPoint property in heft-plugin.json
• Schema files for options provided in heft.json can now be specified using the optionsSchema property in heft-plugin.json and they will be validated by Heft
• Parameters are now defined in heft-plugin.json and are consumed in the plugin via the IHeftTaskSession.parameters or IHeftLifecycleSession.parameters property. NOTE: Other than the default Heft-included parameters, only parameters defined by the calling plugin are accessible
• Plugins can no longer define their own actions. If a plugin requires its own action, a dedicated phase should be added to the consumers heft.json
• The runScript Heft event has been modified to only accept a runAsync method, and the properties have been updated to reflect what is available to normal Heft task plugins
• Path-related variables have been renamed to clarify they are paths (ex. HeftConfiguration.buildFolder is now HeftConfiguration.buildFolderPath)
• The runIncremental hook can now be utilized to ensure that watch mode rebuilds occur in proper dependency order
• The clean hook was removed in favor of the cleanFiles option in heft.json in order to make it obvious what files are being cleaned and when
• As a consequence, plugins can no longer programmatically compute folders to be cleaned by the heft clean command; its behavior is predetermined by static config files, which makes the overall system simpler and more predictable.

Miscellaneous migration notes​

• The node-service-plugin built-in plugin now supports the --serve parameter, to be consistent with the @rushstack/heft-webpack5-plugin dev server.
• If --serve is specified and config/node-service.json is omitted, then node-service-plugin fails with a hard error
• Although @rushstack/heft-lint-plugin and @rushstack/heft-typescript-plugin have been extracted into separate NPM packages, they must be invoked in the same phase, due to their optimized communication using a plugin accessor.

For upgrade instructions, refer to the Heft 0.51 Migration Guide post.

Some key areas that were improved with the updated version of Heft include:

• Developer-defined order of execution for Heft plugins and Heft events
• Partial execution of Heft actions via scoping parameters like --to or --only
• A simplified plugin API for developers making Heft plugins
• Explicit definition of all Heft plugins via heft-plugin.json
• Native support for defining multiple plugins within a single plugin package
• Improved handling of plugin parameters
• Native support for incremental watch-mode in Heft actions
• Reduced overhead and performance improvements
• Much more!

Heft tasks​

Heft tasks are the smallest unit of work specified in heft.json. Heft tasks may take dependencies on other tasks within the same phase, and all task dependencies must complete execution before dependent tasks can execute.

In past releases, we distinguished built-in tasks (copy-files-plugin, node-service-plugin, etc) versus third-party tasks loaded from plugin packages. As of Heft 0.53.0 both kinds of tasks are now declared identically. Built-in plugins simply specify @rushstack/heft as for their plugin packageName.

Heft phases​

Heft phases define a collection of tasks that will run when executing that phase. Phases act as a logical collection of tasks that would reasonably (but not necessarily) map to a Rush phase. Heft phases may take dependencies on other phases, and when executing multiple phases, all selected phases must complete execution before dependent phases can execute.

The heft.json file is where phases and tasks are defined for a given project or rig. Since this file contains the relationships between the phases and tasks, it defines the order of operations for the execution of a Heft action.

Heft actions​

Using similar expansion logic to Rush, execution of a selection of Heft phases can be done through the use of the heft run action. This action executes a set of selected phases in order of phase dependency. If the selected phases are not dependent upon each other, they will be executed in parallel. Selection parameters include:

• --only - Execute the specified phase
• --to - Execute the specified phase and all its dependencies

Additionally, task- and phase-specific parameters may be provided to the heft run action by appending -- <parameters> to the command. For example, heft run --only build -- --clean will run only the build phase and will run a clean before executing the phase.

In addition, Heft will generate actions for each phase specified in the heft.json configuration. These actions are executed by running heft <phaseName> and run Heft to the specified phase, including all phase dependencies. As such, these inferred Heft actions are equivalent to running heft run --to <phaseName>, and are intended as a CLI shorthand.

Watch mode​

Watch mode is now a first-class feature in Heft. Watch mode actions are created for all Heft actions. For example, to run build and test phases in watch mode, either of the commands heft test-watch or heft run-watch --to test. When running in watch mode, Heft prefers the runIncremental hook to the run hook (see Heft Task Plugins).

heft.json structure​

All phases are defined within the top-level phasesByName property. Each phase may specify phaseDependencies to define the order of phase execution when running a selection of Heft phases. Phases may also provide the cleanFiles option, which accepts an array of deletion operations to perform when running with the --clean flag.

Within the phase specification, tasksByName defines all tasks that run while executing a phase. Each task may specify taskDependencies to define the order of task execution. (If taskDependencies is omitted, it defaults to [] and the task only waits for any phaseDependencies of the containing phase.) All tasks defined in taskDependencies must exist within the same phase. For CLI-availability reasons, phase names, task names, plugin names, and parameter scopes, must be kebab-cased.

The following is an example "heft.json" file defining both a build and a test phase:

heft.json example for defining phases and tasks

{
  "$schema": "https://developer.microsoft.com/json-schemas/heft/v0/heft.schema.json",
  "extends": "base-project/config/heft.json",

  // "phasesByName" defines all phases, and each phase defines tasks to be run
  "phasesByName": {
    // ("build" is a user-defined name, not a schema field)
    "build": {
      "phaseDescription": "Transpile and run a linter against build output",
      "cleanFiles": [
        {
          "sourcePath": "temp-build-output"
        }
      ],
      // "tasksByName" defines all tasks within a phase
      "tasksByName": {
        // ("typescript" is a user-defined name, not a schema field)
        "typescript": {
          "taskPlugin": {
            "pluginPackage": "@rushstack/heft-typescript-plugin"
          }
        },
        "lint": {
          "taskDependencies": [ "typescript" ],
          "taskPlugin": {
            "pluginPackage": "@rushstack/heft-lint-plugin",
            "pluginName": "eslint"
          }
        },
        "copy-assets": {
          "taskPlugin": {
            "pluginPackage": "@rushstack/heft",
            "pluginName": "copy-files-plugin",
            "options": {
              "copyOperations": [
                {
                  // NOTE: THIS WAS CALLED "sourceFolder" IN PREVIOUS HEFT VERSIONS
                  "sourcePath": "src/assets",
                  "destinationFolders": [ "dist/assets" ]
                }
              ]
            }
          }
        }
      }
    },

    // ("test" is a user-defined name, not a schema field)
    "test": {
      "phaseDependencies": [ "build" ],
      "phaseDescription": "Run Jest tests, if provided.",
      "tasksByName": {
        // ("jest" is a user-defined name, not a schema field)
        "jest": {
          "taskPlugin": {
            "pluginPackage": "@rushstack/heft-jest-plugin"
          }
        }
      }
    }
  }
}

Lifecycle plugins are specified in the top-level heftPlugins array. Plugins can be referenced by providing a package name and a plugin name. Optionally, if a package contains only a single plugin, a plugin can be referenced by providing only the package name and Heft will resolve to the only exported plugin. Lifecycle plugins can also be provided options to modify the default behavior.

heft.json example for loading a lifecycle plugin

{
  "$schema": "https://developer.microsoft.com/json-schemas/heft/v0/heft.schema.json",
  "extends": "base-project/config/heft.json",

  "heftPlugins": [
    {
      "pluginPackage": "@rushstack/heft-metrics-reporter",
      "options": {
        "disableMetrics": true
      }
    },
    {
      "pluginPackage": "@rushstack/heft-initialization-plugin",
      "pluginName": "my-lifecycle-plugin"
    }
  ]

  // (the "phasesByName" section can also appear here)
}

heft.json property inheritance directives​

Previously, common properties between a heft.json file its extended base file would merge arrays and overwrite objects. Now, both arrays and objects will merge, allowing for simplified use of the heft.json file when customizing extended base configurations.

Additionally, the config file parsers now supports property inheritance directives for customizing how JSON properties get merged when using "extends" inheritance. This system is implemented by the @rushstack/heft-config-file library, and applies to all config files that are loaded using that parser. Overrides are specified by using directives that define inheritance behavior.

For example, assume that we are extending a file with a previously defined exampleObject value that is a keyed object, and a exampleArray value that is an array object:

{
  "$schema": "https://developer.microsoft.com/json-schemas/heft/v0/example-config-file.schema.json",
  "extends": "base-project/config/example-config-file.json",

  "$exampleObject.inheritanceType": "merge", // valid choices are: "merge", "replace"
  "exampleObject": {
    "$exampleObjectMember.inheritanceType": "merge", // valid choices are: "merge", "replace"
    "exampleObjectMember": { ... },

    "$exampleArrayMember.inheritanceType": "append", // valid choices are: "append", "replace"
    "exampleArrayMember": [ ... ]
  },

  "$exampleArray.inheritanceType": "replace", // valid choices are: "append", "replace"
  "exampleArray": [ ... ]
}

Once an object is set to a inheritanceType of override, all sub-property inheritanceType values will be ignored, since the top-most object already overrides all sub-properties.

One thing to note is that different mergeBehavior verbs are used for the merging of keyed objects and arrays. This is to make it explicit that arrays will be appended as-is, and no additional processing (eg. deduplicating if the array is intended to be a set) is done during merge. If such behavior is required, it can be done on the implementation side. Deduplicating arrays within the @rushstack/heft-config-file package doesn't quite make sense, since deduplicating arrays of non-primitive objects is not easily defined.

Associated NPM packages​

Many tasks that were previously built-in to have Heft have been split out into separate NPM packages. The full list:

• @rushstack/heft
• @rushstack/heft-typescript-plugin
• @rushstack/heft-lint-plugin
• @rushstack/heft-api-extractor-plugin
• @rushstack/heft-jest-plugin
• @rushstack/heft-sass-plugin
• @rushstack/heft-storybook-plugin
• @rushstack/heft-webpack4-plugin
• @rushstack/heft-webpack5-plugin
• @rushstack/heft-dev-cert-plugin

Additionally, Rushstack-provided rigs have been updated to be compatible with the new version of Heft:

• @rushstack/heft-node-rig
• @rushstack/heft-web-rig

Authoring Heft plugins​

Lifecycle plugins​

Heft lifecycle plugins provide the implementation for certain lifecycle-related hooks. These plugins will be used across all Heft phases, and as such should be rarely used outside of a few specific cases (such as for metrics reporting). Heft lifecycle plugins provide an apply() method, and here plugins can hook into the following Tapable hooks:

• toolStart - Used to provide plugin-related functionality at the start of Heft execution
• toolFinish - Used to provide plugin-related functionality at the end of Heft execution, after all tasks are finished
• recordMetrics - Used to provide metrics information about the Heft run to the plugin after all tasks are finished

Task plugins​

Heft task plugins provide the implementation for Heft tasks. Heft plugins provide an apply() method, and here plugins can hook into the following Tapable hooks:

• registerFileOperations - Invoked exactly once before the first time a plugin runs. Allows a plugin to register copy or delete operations using the same options as the copyFiles and deleteFiles Heft events (this hook is how those events are implemented).
• run - Used to provide plugin-related task functionality
• runIncremental - Used to provide plugin-related task functionality when in watch mode. If no runIncremental implementation is provided for a task, Heft will fall back to using the run hook as usual. The options structure includes two functions used to support watch operations:
  • requestRun() - This function asks the Heft runtime to schedule a new run of the plugin's owning task, potentially cancelling the current build.
  • watchGlobAsync(patterns, options) - This function is provided for convenience for the common case of monitoring a glob for changes. It returns a Map<string, IWatchedFileState> that enumerates the list of files (or folders) selected by the glob and whether or not they have changed since the previous invocation. It will automatically invoke the requestRun() callback if it detects changes to files or directory listings that might impact the output of the glob.

heft-plugin.json​

The heft-plugin.json config file is a new, required manifest file that must be present in the package folder of all Heft plugin packages. This file is used for multiple purposes, including the definition of all contained lifecycle or task plugins, the definition of all plugin-specific CLI parameters, and providing an optional schema file to validate plugin options that can be passed via heft.json.

The following is an example heft-plugin.json file defining a lifecycle plugin and a task plugin:

{
  "$schema": "https://developer.microsoft.com/json-schemas/heft/v0/heft-plugin.schema.json",

  "lifecyclePlugins": [
    {
      "pluginName": "my-lifecycle-plugin",
      "entryPoint": "./lib/MyLifecyclePlugin.js",
      "optionsSchema": "./lib/schemas/mylifecycleplugin.schema.json",
      "parameterScope": "my-lifecycle",
      "parameters": [
        {
          "parameterKind": "string",
          "longName": "--my-string",
          "description": "…",
          "argumentName": "ARG_NAME",
          "required": false
        }
      ]
    }
  ],

  "taskPlugins": [
    {
      "pluginName": "my-task-plugin",
      "entryPoint": "./lib/MyTaskPlugin.js",
      "optionsSchema": "./lib/schemas/mytaskplugin.schema.json",
      "parameterScope": "my-task",
      "parameters": [
        {
          "parameterKind": "string",
          "longName": "--my-other-string",
          "description": "…",
          "argumentName": "ARG_NAME",
          "required": false
        }
      ]
    }
  ]
}

Cross-plugin interaction​

Sometimes plugins can benefit by communicating with each other. For example, @rushstack/heft-lint-plugin and @rushstack/heft-typescript-plugin share a single TypeScript ts.Program object, which significantly improves build time by avoiding the need to compute the compiler's semantic analysis two times. This optimization brings a constraint that the tasks must share the same Heft phase in your heft.json configuration.

How does this work? Heft plugins can use the requestAccessToPluginByName() API to access the requested plugin accessors. Accessors are objects provided by plugins for external use and are the ideal place to share plugin-specific information or hooks used to provide additional plugin functionality.

Access requests are fulfilled at the beginning of phase execution, prior to clean hook execution. If the requested plugin does not provide an accessor, an error will be thrown noting the plugin with the missing accessor. However, if the plugin requested is not present at all, the access request will silently fail. This is done to allow for non-required integrations with external plugins. For this reason, it is important to implement cross-plugin interaction in such a way as to expect this case and to handle it gracefully, or to throw a helpful error.

Plugins available for access are restricted based on scope. For lifecycle plugins, you may request access to any other lifecycle plugin added to the Heft configuration. For task plugins, you may request access to any other task plugin residing within the same phase in the Heft configuration.

Custom CLI parameters​

Defining CLI parameters is now only possible via heft-plugin.json, and defined parameters can be consumed in plugins via the HeftTaskSession.parameters API. Additionally, all plugin parameters for the selected Heft phases are now discoverable on the CLI when using the --help argument (ex. heft test --help or heft run --to test -- --help).

These parameters can be automatically "de-duped" on the CLI using an optionally-provided parameterScope. By default, parameters defined in heft-plugin.json will be available on the CLI using --<parameterName> and --<parameterScope>:<parameterName>. When multiple plugins provide the same parameter, only the latter parameter will be available on the CLI in order to "de-dupe" conflicting parameters. For example, if PluginA with parameter scope "PluginA" defines --parameter, and PluginB with parameter scope "PluginB" also defines --parameter, the parameters will only be available as --PluginA:parameter and --PluginB:parameter.

If you have any questions or feedback regarding these changes to Heft, please ask in the chatroom or file an issue.

We'll announce new blog posts on Twitter and Mastodon. You can also subscribe directly to the blog's RSS or Atom feeds.

Whereas the website docs are primarily reference material, blog topics may include:

• Announcement details
• Explanations of major changes
• Tips about tech to try out
• Best practices
• Ideas and analyses

If you'd like to contribute a blog post, please contact @octogonz.