Heft and Rig: The New Build Architecture of SPFx

Introduction

With the modernization of the SharePoint Framework (SPFx), Microsoft is transitioning from the traditional Gulp-based build system to a more powerful and standardized toolchain powered by Heft and Rig . This upgrade significantly improves build performance, maintainability, and future compatibility.

What Is Heft?

Heft is a command-line, configuration-driven build orchestrator developed by Microsoft as part of the RushStack ecosystem.

Key Characteristics of Heft

• Heft is NOT GUI-based
  Heft does not provide any graphical interface, visual build designer, or UI tools. It runs entirely from the command line.

• Heft is CLI + Config based
  Heft uses:

  • Command-line commands (heft build)

  • JSON-based configuration files ( heft.json, rig.json)

• No gulpfile.js needed

• Standardized and maintained by Microsoft

• Runs build steps in parallel for better performance

• Provides consistent build behavior across projects

Heft replaces custom scripting with a clean, maintainable, and future-proof build pipeline.

What Is a Rig?

A Rig is a pre-configured build pipeline package that Heft loads to run your project's build system.

For SPFx, the rig used is:

@microsoft/spfx-rig

It contains all predefined SPFx build rules such as:

• TypeScript compilation

• Webpack bundling

• SCSS build

• Localization compilation

• Manifest generation

• Packaging and deployment pipeline

Purpose of a Rig

• Standardize build logic

• Remove the need for custom Gulp tasks

• Provide faster and cleaner updates

• Minimize configuration effort for developers

Why SPFx Moved from Gulp to Heft + Rig

This modernization brings SPFx closer to modern engineering practices used inside Microsoft teams.

How Heft Works with a Rig

The relationship can be summarized as:

• Heft = Engine

• Rig = Blueprint / Pipeline Definition

Heft loads the rig and executes the build exactly as defined by Microsoft.

Step-by-Step: Heft-Based SPFx Build Flow

Step 1: Create an SPFx Project

When you create a new SPFx project (v1.20+), it is Heft-based by default .

yo @microsoft/sharepoint 

No 'gulp.js' is created.

Step 2: Heft-Based Project Structure

Key configuration files:

config/
  heft.json
  rig.json
  serve.json
src/
package.json

• heft.json - Defines build actions

• rig.json- Points to SPFx rig

• package.json- Maps npm scripts to Heft

Step 3: Rig Configuration

SPFx loads its build pipeline from the rig.

{
  "rigPackageName": "@microsoft/spfx-rig",
  "rigProfile": "default"
}

This tells Heft to use Microsoft’s predefined SPFx build rules.

Step 4: Heft Loads the SPFx Rig

Internally:

1. Heft starts

2. Reads rig.json

3. Loads @microsoft/spfx-rig

4. Registers all SPFx build plugins (TS, Webpack, SCSS, localization, packaging)

Step 5: Run Build Commands

All commands are CLI-based:

npm run build
npm run bundle -- --production
npm run package-solution -- --production

Heft orchestrates everything—no custom tasks required.

Step 6: TypeScript Compilation

• Uses incremental TypeScript compilation

• Configuration from 'config/typescript.json'

• Faster than Gulp-based compilation

Step 7: Webpack Bundling

• Uses Webpack 5

• Bundles web parts and extensions

• Outputs files to the dist folder

Step 8: SCSS and Localization

• SCSS compiled automatically

• Localization files processed

• Language bundles generated without manual setup

Step 9: Local Development

npm run serve 

• Builds solution

• Starts local workbench

• Watches file changes

• Rebuilds incrementally

Step 10: Package and Deploy

npm run package-solution -- --production 

Output

sharepoint/solution/*.sppkg 

Upload the package to the App Catalog for deployment.

Architecture Diagram

Heft & Rig (New SPFx Architecture)

heft.json / rig.json- Heft (CLI + Config-based engine)- Loads SPFx Rig (predefined build system)- TypeScript/Webpack/SCSS/Manifest/Packaging

Developer Experience Before and After

Before (Gulp)

• Manually write gulpfile.js

• Maintain dozens of plugins

• Fix frequent version conflicts

• Difficult to upgrade SPFx versions

Now (Heft + Rig)

• No gulpfile

• No manual tasks

• Faster builds

• Easy updates with rig packages

• Predictable, stable build behavior

Conclusion

Heft is a modern, CLI-based build orchestrator that offers a clean, standardized way of building SPFx projects. It is not GUI-based i.e all operations run through command-line tools and configuration files. Rigs act as pre-built templates that define how Heft should run.

Together, Heft + Rig replace Gulp and provide a stable, future-proof foundation for SharePoint Framework development.