With the release of SPFx v1.22, Microsoft introduced Heft as the new build engine, replacing Gulp. This change brings better performance, modern tooling, and a more standardized approach to building SPFx solutions. In this blog, we’ll explore what this means for developers and how to upgrade.
What is Gulp in SPFx?
In SharePoint Framework (SPFx), Gulp is a JavaScript-based task runner that was traditionally used to automate build and development tasks.
What Gulp Did in SPFx
Historically, the SharePoint Framework (SPFx) relied on Gulp as its primary task runner, responsible for orchestrating the entire build pipeline. Gulp did a series of scripted tasks, defined inside gulpfile.js and in different SPFx build rig packages. These tasks automate important development and packaging workflows.These tasks included:
- Automates repetitive tasks such as:
- TypeScript to JavaScript.
- Bundling multiple files into optimized packages.
- Minifying code for better performance.
- Packaging the solution into a “.sppkg” file for deployment.
- Runs development servers for testing (gulp serve).
- Watches for changes and rebuilds automatically during development
Because these tasks depended on ad‑hoc JavaScript streams and SPFx‑specific build rig wrappers, the pipeline could become complex and difficult to extend consistently across projects.
The following are the common commands included in gulp:
- gulp serve – local workbench/dev server
- gulp build – build the solution
- gulp bundle – produce deployable bundles
- gulp package-solution – create the .sppkg for the App Catalog
What is Heft?
In SharePoint Framework (SPFx), Heft is the new build engine introduced by Microsoft, starting with SPFx v1.22. It replaces the older Gulp-based build system.
Heft has replaced Gulp to support modern architecture, improve performance, ensure consistency and standardization, and provide greater extensibility.
Comparison between heft and gulp:
| Area | Gulp (Legacy) | Heft (SPFx v1.22+) |
|---|---|---|
| Core model | Task runner with custom JS/streams (gulpfile.js) |
Config‑driven orchestrator with plugins/rigs |
| Extensibility | Write custom tasks per project | Use Heft plugins or small “patch” files; standardized rigs |
| Performance | Sequential tasks; no native caching | Incremental builds, caching, unified TypeScript pass |
| Config surface | Often scattered across gulpfile.js and build rig packages |
Centralized JSON/JS configs (heft.json, Webpack patch/customize hooks) |
| Scale | Harder to keep consistent across many repos | Designed to scale consistently (Rush Stack) |
Installation Steps for Heft
- To work with the upgraded version, you need to install Node v22.
- Run the command npm install @rushstack/heft –global
Removing Gulp from an SPFx Project and Adding Heft (Clean Steps)
- To work with the upgraded version, install Node v22.
- Remove your current node_modules and package-lock.json, and run npm install again
- NOTE: deleting node_modules can take a very long time if you don’t skip the recycle bin.
- Open PowerShell
- Navigate to your Project folder
- Run command Remove-Item -Recurse -Force node_modules
- Run command Remove-Item -Force package-lock.json
- Open the solution in VS Code
- In terminal run command npm cache clean –force
- Then run npm install
- Run the command npm install @rushstack/heft –global
After that, everything should work, and you will be using the latest version of SPFx with heft. However, going forward, there are some commands to be aware of
Day‑to‑day Commands on Heft
- heft clean → cleans build artifacts (eq. gulp clean)
- heft build → compiles & bundles (eq. gulp build/bundle) (Note— prod settings are driven by config rather than –ship flags.)
- heft start → dev server (eq. gulp serve)
- heft package-solution → creates.sppkg (dev build)
- heft package-solution –production → .sppkg for production (eq. gulp package-solution –ship)
- heft trust-dev-cert → trusts the local dev certificate used by the dev server (handy if debugging fails due to HTTPS cert issues
Conclusion
Upgrading from Gulp to Heft in SPFx projects marks a significant step toward modernizing the build pipeline. Heft uses a standard, configuration-based approach that improves performance, makes things the same across projects, and can be expanded for future needs. By adopting Heft, developers align with Microsoft’s latest architecture, reduce maintenance overhead, and gain a more scalable and reliable development experience.
