Heft-based Toolchain in SPFx – Migration from Gulp

Introduction

Starting from SPFx 1.22, Microsoft officially replaced the traditional Gulp-based build system with a modern Heft-based toolchain powered by RushStack.

This is one of the biggest architectural changes in SPFx history and brings SharePoint development in line with how Microsoft builds large-scale applications internally (like Teams and Office).

In this article, we will cover:

• Why Microsoft moved away from Gulp
• What Heft is
• Benefits of the new toolchain
• How to migrate existing projects
• How to run, build, and ship SPFx solutions

Why Microsoft Replaced Gulp

Gulp served SPFx well for many years, but it had several limitations:

• Hard to customize without internal hacks
• Slow builds in large projects
• No standard configuration across projects
• Plugins frequently broke during upgrades
• Difficult to maintain in CI/CD

Microsoft already uses RushStack + Heft internally for:

• Microsoft Teams
• Office Web
• VS Code Extensions

So SPFx now uses the same enterprise-grade build system.

What is Heft?

Heft is a modern build orchestrator developed by RushStack.

It replaces multiple tools like:

• Gulp
• Webpack scripts
• Jest runners
• ESLint orchestration

With a single unified system.

Heft handles:

• TypeScript compilation
• Bundling
• Linting
• Testing
• Packaging

All with one CLI.

Benefits of Heft in SPFx

1. Faster Builds

Heft runs tasks in parallel and caches results, making builds significantly faster.

2. Zero Webpack Knowledge Required

Webpack still exists internally, but you rarely need to touch it.

3. First-Class TypeScript Support

No more custom tsconfig hacks or broken builds.

4. Standardized Tooling

Every SPFx project now follows the same build structure.

5. Enterprise Ready

This is the same toolchain used by Microsoft engineers.

Old vs New Commands

Example package.json (SPFx 1.22+)

{
  "scripts": {
    "build": "heft test --clean --production && heft package-solution --production",
    "start": "heft start --clean",
    "clean": "heft clean",
    "eject-webpack": "heft eject-webpack"
  }
}