SPFx 1.22: Transitioning from Gulp to Heft for Modern SharePoint Development

The SharePoint Framework (SPFx) has long been the backbone for building modern experiences in SharePoint and Teams development. Since its launch from 2017, developers have relied on the gulp-based toolchain to build, bundle and deploy their solutions.

In December 2025, Microsoft released the new release for the SPFx 1.22. This release entirely shifts from gulp-based toolchain to Heft.

Gulp based toolchain

From initial stage onwards (v1.o to v1.21) SharePoint framework depends on gulp-based toolchain. This system orchestrated tasks like compiling Typescript, bundling with webpack, and packaging solutions. Over the period, the gulp tasks changed to custom built for SPFx. This causes the below issues and problems,

Outdated dependencies: The gulp-core-build stack was rarely updated, leading to frequent npm audit warnings and security concerns
Limited Customization: Developers struggled to extend or modify the build process.
Minimal maintenance: With little ongoing support, technical debt accumulated, making the toolchain fragile and harder to sustain.

Shifting to Heft

Heft is a config-driven build orchestrator developed as part of the Ruh Stack ecosystem. Unlike gulp, which helps developers writing custom JavaScript tasks to handle builds. Heft takes a standardized and declarative approach. It defines tasks through configuration files, making the build process more transparent, predictable and easier to extend.

Still Heft uses the webpack to handle bundling, manifest generation and localization. The Heft plugins ensure the compatibility with existing SPFx features. This helps developers to customize the webpack via Heft’s APIs or eject for full control.

Why the change matters?

Based on my thoughts, this change can reshape the SPFx development experience and it sets the stage to make the SPFx generator as open source in upcoming months. This change addressed the long-standing pain points and lays the foundation for a modern, scalable and developer-friendly ecosystem.

Reduce outdated dependencies

SPFx developers aware about the problem in getting audit warnings and errors by using gulp tasks. Because we depend on the gulp tasks and its outdated package. Heft is actively maintained, secure and aligned with the modern web standards =, reducing vulnerabilities and ensuring long-term stability.

Configuration driven builds

Developers frequently struggled with hidden “black box” build steps in gulp

Heft introduces a transparent, config-driven workflow with a plugin architecture, making customization cleaner and easier. This helps developers to extend builds without struggling on alternative way of creating custom JavaScript tasks.

Unified ecosystem

Based on the Microsoft documentation, the internal team from Microsoft already moved away from gulp a long back.

With Heft, both Microsoft and the developer community can now share the same toolchain. This update accelerates feature delivery and ensures improvements benefits equally.

Future Proofing

Heft is designed for scalability, supporting large projects and monorepos with ease.

Advanced features like incremental compilation, filesystem caching, and performance tracking make builds faster and more efficient.

This helps the SPFx for long-term growth and adaptability in modern development environments.

Gulp	Heft
Script-based, task runner approach	Config-driven, declarative build system
Developers wrote custom tasks in JavaScript	Uses config files in JSON (heft.json, rig.json, etc) instead of custom logic
Build steps often hidden inside a “black box”	Provided shared rigs for consistency across projects
Limited extensibility and plugin support	Plugin-friendly architecture for clean extensions

The Next Step

1. Install Node.js (Jod Version)

To begin setting up your development environment, install the Jod version of Node.js. This specific version is required for compatibility with the tools and libraries used in this workflow.

2. Install Required Global npm Packages

Next, install the following npm packages globally to ensure all necessary tooling is available:

@rushstack/heft
Yo
@microsoft/generator-sharepoint

You can install all these packages at once by running the following command in your terminal:

npm install @rushstack/heft yo @microsoft/generator-sharepoint --global

3. Enable Trust Mode for Localhost Testing

To enable trust mode for localhost while in testing mode, use the following command:

heft trust-dev-cert

This will allow your development environment to run securely on your local machine.

4. Ready to Create SPFx Web Parts and Extensions

Once you have completed the above setup steps, you are ready to create SPFx web parts and extensions using Rush Stack.

Conclusion

Staying aligned with Microsoft standards is essential for modern SharePoint development. With the transition to the Rush Stack and Heft-based toolchain in SPFx 1.22, we’ve begun migrating our product and services projects to this new model to stay ahead of the roadmap. This shift has streamlined our SharePoint development process, reduced build and packaging time, and improved overall maintainability allowing us to deliver scalable, future-ready solutions more efficiently.

Building SPFx solutions with the new Heft toolchain?

Talk to Our Experts