The SharePoint Framework (SPFx) version 1.22 marks a significant evolution in its build system, transitioning from a custom Gulp-based toolchain to the more robust, config-driven Heft orchestrator. This change, while keeping Webpack as the underlying bundler, addresses long-standing technical debt, aligns Microsoft's internal development practices with the external community

Microsoft has been very clear on this point to ensure a smooth transition for the community.

Important Projects that upgrade their package. Json to reference SPFx v1.22 or later can continue using gulp and existing customizations without breaking changes. The new toolchain only affects newly generated projects and those that choose to migrate projects to SPFx v1.22 or later.

The transition is being phased in, giving teams ample time to plan their migration. Here’s the timeline:

SPFx v1.22: New projects default to Heft. Existing projects can upgrade and continue using Gulp, which receives only critical breaking fixes.
SPFx v1.23: The v1.22 support model continues, with both toolchains supported for existing projects.
SPFx v1.24+: The Gulp toolchain becomes officially unsupported. All new development and fixes will focus exclusively on Heft.

This transition affects several key areas:

Task Orchestration: The JavaScript-based gulpfile.js is replaced by declarative JSON configuration files, primarily heft.json.
Project Configuration: New projects include files like rig.json, which references a shared configuration package to minimize boilerplate and ensure consistency.
Developer Workflow: npm scripts in package.json are updated to call Heft commands instead of Gulp tasks, and legacy gulpfile.js customizations are no longer compatible.

Key Heft Concepts

Actions & Phases: An "action" is a command-line verb (e.g., heft build) that typically maps to a "phase." A phase contains a collection of tasks. Key SPFx phases include build, test, and package-solution.
Tasks: A task is a specific operation within a phase, such as compiling TypeScript or packaging a solution.
Plugins: A Heft plugin defines a task's logic and its configuration schema. The SPFx rig utilizes plugins for Sass, TypeScript, Webpack, Jest, and more.
Rigs: A rig is a standardized, shareable set of configurations (phases, tasks, and settings) packaged into an npm package. SPFx projects use the @microsoft/spfx-web-build-rig package, which contains the default build profile. This significantly reduces the amount of configuration needed within an individual project.

Mapping Gulp Tasks to Heft Commands

Heft actions and phases are analogous to tasks in the legacy Gulp toolchain.

Conclusion: A Foundation for the Future

The transition to Heft is not a simple replacement of one task runner for another. It is a deliberate evolution of the SharePoint Framework, moving towards a more stable, sustainable, and unified development experience. By aligning the internal and external toolchains and shifting to a declarative configuration model, Microsoft has laid a more robust foundation for the future of SPFx.

Evolution of the SPFX: Heft-Based Build Toolchain