In the first article, we explored what HEFT is and why it was introduced into the SharePoint Framework. Now we turn to the practical side of the conversation: how HEFT actually works when you build a SharePoint Framework (SPFx) solution.
Although developers still run familiar commands such as build, serve, and package-solution, the underlying system executing those commands has changed. HEFT now orchestrates the entire toolchain behind the scenes. Understanding its workflow does not require deep technical knowledge of its internal configuration files. Instead, it requires understanding how HEFT structures work into phases and tasks, how it relies on the SPFx rig, and how it executes plugins in a predictable order.
The Foundation: Phases and Tasks
HEFT organizes work into phases, and each phase contains one or more tasks. This structure replaces the older script-driven approach previously used in SPFx.
A phase represents a logical stage in the build lifecycle. For example, there are phases for building, testing, and packaging. Each phase defines what types of work must occur at that stage.
Inside each phase are tasks. A task performs a specific responsibility, such as compiling TypeScript, processing Sass, running tests, or bundling assets. Tasks are implemented through plugins and are executed in a defined sequence.
This structured model means that HEFT does not simply run commands in order. Instead, it evaluates the current phase, identifies the tasks attached to it, and executes them according to the configuration defined by the SPFx rig and your project’s configuration files.
The SPFx Rig: Where the Defaults Come From
Every SPFx project references a rig configuration. The rig defines the default build behavior for SharePoint Framework projects.
The SPFx rig specifies:
- Which phases are available
- Which tasks belong to those phases
- Which plugins implement those tasks
- The default configuration for those plugins
Because your project references the rig, you inherit a complete build pipeline without having to define it manually. This is important because it ensures consistency across all SPFx projects and allows Microsoft to evolve the toolchain while maintaining compatibility.
When HEFT runs, it first loads the rig configuration, then applies any project-level configuration overrides. This layered approach ensures that the default pipeline remains stable while still allowing controlled customization.
What Happens When You Run a Build Command
From a developer’s perspective, building an SPFx project looks straightforward. You run a command such as npm run build. However, under the hood, HEFT follows a structured process.
- First, HEFT loads your project configuration and resolves the rig reference. This tells HEFT which phases and tasks are available for execution.
- Next, HEFT activates the requested phase. For a standard build, this is the build phase. The build phase contains tasks such as TypeScript compilation and asset processing.
- HEFT then executes the tasks in the order defined by the rig. For example, TypeScript compilation must complete before bundling can occur. If a task fails, HEFT stops the phase and clearly reports the error.
- Once compilation and preprocessing tasks are completed successfully, HEFT invokes the bundling step. This uses webpack internally, but HEFT controls when and how webpack is executed.
- After bundling completes, HEFT produces the expected output artifacts, such as compiled JavaScript and processed assets.
Because the workflow is defined declaratively, every execution of the build phase follows the same sequence.
A Simple Practical Example
To make this clearer, consider a basic SPFx web part project created with the standard generator.
The project includes:
- TypeScript source files
- SCSS styles
- A manifest file
- Static assets
You run the build command.
Here is what HEFT does conceptually.
- HEFT reads your project configuration and determines that it is an SPFx solution using the SPFx rig. It activates the build phase defined in that rig.
- The first task compiles TypeScript files. If there are type errors, the build fails at this stage.
- Once TypeScript compilation succeeds, HEFT runs the Sass processing task. Styles are transformed and prepared for bundling.
- Next, HEFT runs the webpack task. The webpack configuration is generated according to the SPFx rig. If you have not customized it, the default configuration is used. Webpack bundles your solution into optimized output files.
- Finally, HEFT completes the phase and produces the build output.
At no point are you writing custom build scripts or manually chaining tasks. The entire workflow is orchestrated through phases, tasks, and configuration.
Included Plugins in the Workflow
HEFT uses plugins to implement tasks. The SPFx toolchain includes built-in plugins for common activities such as:
- TypeScript compilation
- Sass processing
- Jest testing
- Webpack bundling
- Running additional scripts
Each plugin is responsible for one aspect of the build. HEFT coordinates them rather than embedding their logic directly into the core engine. This plugin model improves modularity. If a plugin needs to be configured, you modify its configuration file. If a new capability is required, it can be added as a separate plugin instead of rewriting the pipeline.
How Custom Code Fits into the Workflow
The workflow also allows custom logic through documented extension points. If you need to run custom code during the build, the Run Script Plugin lets you register a script file to execute in a specific phase. HEFT treats that script as part of the pipeline.
If you need to adjust how webpack behaves, the Webpack Patch Plugin lets you modify the generated webpack configuration before bundling. Both mechanisms operate within the structured phase and task model. They do not replace the pipeline. They integrate into it.
This design preserves stability while allowing flexibility.
Migration Context: From Gulp to HEFT
In the previous Gulp-based toolchain, developers commonly modified gulpfile.js to inject custom behavior. That approach relied on imperative scripts and custom task definitions.
The HEFT model replaces that with:
- Configuration-driven phase definitions
- Plugin-based task execution
- Structured extension points
The migration documentation emphasizes that although the underlying orchestration system has changed, the user-facing experience remains familiar. Developers still use standard commands, and SPFx projects still produce the same outputs.
The key difference is how those outputs are generated and managed internally.
Why This Workflow Is Important
The HEFT workflow improves predictability and maintainability. Because tasks are explicitly defined and executed in known phases, the build process is easier to reason about.
This structured approach also improves reliability in automated environments such as CI/CD pipelines. The same phase-based workflow runs locally and in build agents, reducing discrepancies between development and production builds.
Most importantly, the workflow is designed to evolve. Since tasks are implemented through plugins and configured declaratively, improvements to the toolchain can be delivered through updated rig definitions rather than rewriting individual projects.
Conclusion
HEFT’s workflow in SPFx is built around clear phases, modular tasks, and configuration-driven execution. When you run a build command, HEFT loads the SPFx rig, activates the appropriate phase, executes its tasks in order, and produces predictable output.
Although the visible developer experience has not changed dramatically, the underlying orchestration model is significantly more structured than before. That structure is what enables safer customization, smoother upgrades, and long-term sustainability for SPFx solutions.