The following concepts are important for understanding Heft's design:
- action - a Heft command-line verb (as formalized by Rush Stack's ts-command-line system). For example, the "test" action appears in the
heft test --cleancommand. Actions are the user interface, essentially macros tailored for typical developer activities.
- plugin - a TypeScript class that implements the
IHeftPlugincontract to provide arbitrary functionality. Plugins are loaded optionally based on Heft's configuration.
- plugin package - an NPM package that provides one or more Heft plugins. You can create your own NPM package that exports custom plugins for Heft to use. See Core Plugins for a list of the built-in plugins.
- hook - Heft leverages Webpack's tapable system for enabling plugins to register handlers for various events during the build.
- task - a conceptual Heft operation that produces an output, typically by invoking some tool. For example,
eslintare Heft tasks. Unlike in other systems, Heft's tasks are not a formal coding contract or component; for example the
TypeScriptPluginobject implements three separate tasks (
tslint) whose code is closely integrated.
- stage - a larger sequence of work encompassing multiple Heft tasks. When invoking Heft, the command line typically selects a meaningful set of stages to run. The stage names are also used to group logging output. Examples of Heft stages: "clean", "build", "test"
- rig package - an NPM package that provides Heft configurations that can be reused across multiple projects with similar requirements See the @rushstack/rig-package documentation for details about this system.
- rig profile - a named configuration obtained from a rig package. A single rig package can provide more than one configuration. For example, it might provide separate profiles for application projects versus library projects.
Future plans: Today Rush commands can only invoke Heft actions. However, in the future we want to implement a "multiphase build" feature that will enable Rush to orchestrate more granular steps of work. For example, once a library dependency has compiled its output, Rush could start building the application before the library finishes running its unit tests. This feature will bring some additional jargon:
- command - A monorepo command-line action as defined globally in command-line.json.
- phase - This is similar to Heft's "stage", except that phases will be defined globally so that Rush can model their dependency relationships.