Heft in SharePoint Framework (SPFx): Understanding the Shift from Gulp

What is Heft

Heft is a modern, configuration-driven build orchestrator developed by Microsoft as part of the Rush Stack ecosystem. It does not replace tools like TypeScript, Webpack, or ESLint, but coordinates them in a predictable and structured manner using JSON configuration.

It brings clarity, maintainability, and consistency to SPFx build processes.

Why Heft Instead of Gulp

The earlier Gulp-based toolchain introduced several challenges as SPFx matured:

• Gulp required writing JavaScript code to define tasks (imperative). Heft uses JSON config files (declarative) — easier to read and maintain.
• The Gulp setup was a custom, SPFx-only solution. It was hard to extend without breaking things.
• Gulp tasks ran sequentially by default. Heft runs tasks in parallel where possible, giving faster builds.
• The build pipeline was a ‘black box’ — hard to understand what was happening. Heft is transparent and inspectable.
• Older Gulp-based templates had npm audit security vulnerabilities. SPFx v1.22 with Heft starts clean.
• No native TypeScript-first support in Gulp — TypeScript needed wrapper libraries. Heft treats TypeScript as a first-class citizen.

Heft addresses these with a declarative and extensible architecture.

Heft vs Gulp — Advantages

Gulp (Legacy) — The Old Way

• JavaScript code to define tasks
• Sequential, slower builds
• Hard to extend, config was a black box
• npm audit vulnerabilities
• Deprecated from SPFx v1.24

Heft (New) — The Future

• JSON config files, zero code
• Parallel execution, faster builds
• Clean plugin architecture, fully transparent
• Clean security baseline
• Actively maintained

Heft Command Reference

• heft trust-dev-cert : Trusts the local SSL certificate (run once during setup)
• heft start : Starts the local development server
• heft start –clean : Cleans previous artifacts and starts the development server
• heft build : Compiles TypeScript, processes Sass, and runs linting
• heft build –production : Creates an optimized production build
• heft test : Runs Jest unit tests
• heft test –clean –production : Executes full CI pipeline: clean, test, and production build
• heft package-solution –production : Generates the .sppkg file for SharePoint deployment
• heft clean : Removes all build artifacts
• heft dev-deploy : Deploys assets to a testing CDN
• heft eject-webpack : Ejects webpack configuration (advanced use)

Required Packages

Global Installation (one-time, on your machine)

# Node.js v22 is required for SPFx v1.22
# Install using Fast Node Manager (recommended):
fnm install 22 && fnm use 22

# Install Heft CLI globally
npm install -g @rushstack/heft

# Install Yeoman + SPFx generator (if not already installed)
npm install -g yo @microsoft/generator-sharepoint 

Project devDependencies (inside your SPFx project)

These are automatically included when you scaffold a new project with yo @microsoft/sharepoint in SPFx v1.22. If migrating an older project, install them manually:

npm install --save-dev --save-exact \
  @rushstack/heft@1.1.2 \
  @microsoft/spfx-web-build-rig@1.22.1 \
  @microsoft/spfx-heft-plugins@1.22.1 \
  @microsoft/eslint-config-spfx@1.22.1 \
  @microsoft/eslint-plugin-spfx@1.22.1 \
  @rushstack/eslint-config@4.5.2 \
  @microsoft/sp-module-interfaces@1.22.1 \
  @types/heft-jest@1.0.2 \
  @typescript-eslint/parser@8.46.2 

• @rushstack/heft The Heft build orchestrator (CLI and core engine)
• @microsoft/spfx-web-build-rig Defines SPFx build phases, tasks, and default configurations
• @microsoft/spfx-heft-plugins Provides SPFx-specific Heft plugins for packaging and manifest generation
• @microsoft/eslint-config-spfx ESLint configuration tailored for SPFx projects
• @microsoft/eslint-plugin-spfx Custom ESLint rules specific to SPFx development
• @rushstack/eslint-config Base ESLint configuration from the Rush Stack ecosystem
• @microsoft/sp-module-interfaces TypeScript interfaces for SPFx modules
• @types/heft-jest Type definitions for Jest testing in Heft-based projects
• @typescript-eslint/parser Enables ESLint to parse and lint TypeScript code

Configuration Model

Heft introduces a rig-based configuration system.

The rig.json file replaces the traditional gulpfile.js and defines:

• Build phases such as build, test, and packaging
• Toolchain configuration (TypeScript, Webpack, ESLint, Sass)
• Standardized structure across projects

This reduces manual configuration and improves maintainability.

Adoption Timeline

• SPFx v1.22 (Dec 2025) : Heft becomes the default for new projects, while Gulp moves into maintenance mode
• SPFx v1.23 (April 2026) : Introduction of the new CLI with a transition window for existing projects
• SPFx v1.24+ (June 2026) : Gulp is retired and Heft becomes the only supported build engine

Conclusion

Heft represents a shift toward modern, scalable, and maintainable build systems within SPFx. By moving from imperative scripts to declarative configuration, it improves developer experience, performance, and long-term sustainability.

For developers working in SharePoint and Microsoft 365 ecosystems, understanding Heft is now essential.

About the author

A, Khatua (27/10/2026) (5) Heft in SharePoint Framework (SPFx): Understanding the Shift from Gulp | LinkedIn