The SharePoint Framework (SPFx) v1.22 release is here, and it’s a BIG one. Unlike previous releases that introduce new features, this release has no new features or fixes. Instead, this release includes three major changes to the “behind the scenes” aspect of SPFx projects:
- Clean npm audit reports (finally!)
- TypeScript v5.8 upgrade
- New Heft-based build toolchain
Let’s unpack what’s new and what it means for your development workflow.
What’s new?
Clean npm audits (finally!)
If you’ve been an SPFx developer for any length of time, you’re familiar with the report of dozens of npm package vulnerabilities, many marked as high or critical, all tied to dependencies deep within the Microsoft toolchain packages.
With SPFx v1.22, Microsoft invested a lot of time to update dependencies with the goal of eliminating everything from running npm audit on your project after installing dependencies.
Don’t expect this to hold true forever as there may be an issue discovered in a dependency after the release… but at least when SPFx v1.22 is released, we’ll see near-zero list of findings.
This matters because security teams at enterprise organizations often flag these vulnerabilities during code reviews, even when the vulnerable packages only run during development and never make it to production. Now you can confidently show a clean audit report.
TypeScript v5.8 by default
New projects scaffolded with SPFx v1.22 use TypeScript v5.8 by default. This is a significant jump from previous versions and brings all the modern TypeScript features you’ve been missing.
For context, in my SPFx v1.20 unboxing, I complained that SPFx was still using TypeScript v4.7.4, which was over two years old at the time. Microsoft listened, and now SPFx developers have access to the latest TypeScript capabilities without workarounds.
Major toolchain overhaul: ditching gulp in favor of Heft
While it may not seem like a big deal, this one will have the biggest impact with this release.
The SPFx v1.22 release introduces a fundamental shift in how projects are built. The legacy gulp-based toolchain that’s been with SPFx since v1.0 back in 2017 is being replaced with a Heft-based toolchain.
What Is Heft?
Heft is a config-driven toolchain that orchestrates popular tools like TypeScript, ESLint, Jest, webpack, and API Extractor. Think of it as a replacement for gulp, but instead of writing JavaScript code to define your build tasks, you configure them through JSON files. Learn more about Heft from its documentation: heft.rushstack.io.
The key philosophy is replacing special-purpose scripts with a reusable, config-driven engine. Rather than each project maintaining its own custom build setup, Heft encourages defining standardized project types called rigs that projects can inherit from.
That’s right - gulp is gone, replaced by Heft! This is what I want to explore a bit more in this article.
This article focuses on what’s new with the SPFx v1.22 release. Refer to the following articles on how to customize and extend the new Heft-based toolchain:
Learn four ways to customize the SharePoint Framework v1.22 Heft build toolchain: built-in plugins, custom scripts, and ejecting webpack for full control.
https://www.voitanos.io/blog/sharepoint-framework-customize-heft-toolchain-plugins-scripts-webpack/
Learn how to add Stylelint to your Heft-based toolchain projects using a custom plugin. Use my @voitanos/heft-stylelint-plugin or build your own from scratch.
https://www.voitanos.io/blog/heft-create-custom-plugin-stylelint/
Understanding the new toolchain
Before diving into what changed, let’s understand the key players in this new architecture.
How the pieces fit together
Let me break down each component:
- Task: An individual operation with specific options. Some examples of tasks include copying or deleting files, compiling TypeScript or Sass files, linting your code, running webpack, and more.
- Phase: A stage like build or package-solution that groups related tasks. You can think of a phase as serving the same role that a task served in the legacy gulp-based toolchain.
- heft.json: The primary configuration file that specifies the phases (aka: commands) you’ll run with the Heft CLI, the tasks within each phase, and their configurations.
- Rig: A predefined Heft configuration within a rig package that projects can inherit. The rig contains a heft.json file with phases, tasks, and task configurations. For example, in the case of SPFx, Microsoft created a SPFx rig that defines all the phases, tasks and the task configurations used within an SPFx project.
- rig.json: A configuration file in your project that references a shared configuration package. This minimizes duplication across projects.
- Rig Package: An npm package containing one or more rigs. Each of the rigs is also referred to as a profile. The package can contain a default profile, literally named default, so that when a project references the package, they don’t have to specify the profile they want to use. For SPFx, this is @microsoft/spfx-web-build-rig.
Why the toolchain is changing
The decision to move from gulp to Heft addresses several long-standing challenges.
Technical debt
The gulp-based toolchain was a custom solution built specifically for SPFx. Over time, it accumulated significant technical debt with minimal maintenance. This resulted in those notorious npm audit warnings from outdated dependencies in the unmaintained gulp-core-build stack.
Here’s the part that frustrated many developers: Microsoft internally moved away from this toolchain years ago, creating a split between what Microsoft used internally and what external developers had to work with. That split is now closing.
Community feedback
Since 2020, the SPFx community has consistently requested more flexibility for build customizations. The old toolchain had real limitations. Many build steps were obfuscated, creating a “black box” that was difficult to understand and extend. There was no true plugin architecture for clean customizations. Developers who needed to customize their builds resorted to complex workarounds, hacking into gulp tasks and modifying generated webpack configurations.
Better alignment
Moving to Heft means Microsoft’s internal development practices align with what external developers use. Both first-party teams and third-party developers now work with the same build system. This should translate to faster feature delivery since improvements benefit everyone simultaneously.
What changed in the toolchain
Core replacement
The gulp-based toolchain (gulp-core-build) is replaced with Heft as the primary task orchestrator. Webpack continues handling the bundling, but it’s now orchestrated through Heft rather than gulp tasks. The npm scripts in package.json call Heft commands instead of gulp tasks.
New configuration files
Projects built with the new toolchain include several configuration files located in the ./config folder in your SPFx v1.22 project:
- heft.json: Specifies build tasks and configurations
- You’ll notice this is missing from a new SPFx v1.22 project. This file isn’t necessary in this case because an SPFx project is configured to use the SPFx rig that’s installed as a dependency and referenced in the ./config/rig.json. As I explained above, the rig contains the heft.json file with the configuration.
- rig.json: References the shared SPFx configuration package
- typescript.json: Manages TypeScript Heft plugin settings
- sass.json: Manages the Sass Heft plugin settings
These last two plugin settings files warrant a bit more explanation.
You can set the options for a plugin directly in the heft.json file, or in the ./config folder as a JSON file. If you use the JSON file option to configure plugins, you can customize the plugin options from your own project, including extending the rig’s configuration using the extends property as shown in the default ./config/sass.json:
{
"$schema": "https://developer.microsoft.com/json-schemas/heft/v0/heft-sass-plugin.schema.json",
"extends": "@microsoft/spfx-web-build-rig/profiles/default/config/sass.json"
}
Project generation changes
When creating new SPFx projects with the Yeoman generator v1.22:
- All new projects use the Heft-based toolchain by default
- New configuration files supporting the Heft architecture are included
- The generator provides a
--use-gulpoption for developers who need the legacy toolchain during transition
My Take - Don't Use `--Use-Gulp`
The SPFx v1.22 release only includes updates to the toolchain. Therefore, if you upgrade your SPFx project to v1.22, you’re doing it to adopt the Heft-based toolchain. In this case, why keep gulp around?
If you aren’t ready to adopt the new toolchain, then stick with the version of SPFx your project is currently on. But you’ll eventually need to upgrade your project at some point.
Developer workflow changes
If you have existing toolchain customizations, they won’t work with the new toolchain. The ./gulpfile.js file is eliminated, with external library configurations now handled in different ways. I’ll address the customization options below.
Support timeline
Microsoft has established a phased transition:
SPFx v1.22
- New projects default to Heft
- Legacy gulp option available via
--use-gulpflag - Existing projects can continue using gulp without modification
- Both toolchains supported, but gulp receives only critical fixes
SPFx v1.23 (Planned)
- New projects exclusively support Heft
- Existing projects can still use gulp-based builds
- Both toolchains supported with critical-only fixes for gulp
SPFx v1.24 and Beyond
- Gulp toolchain becomes officially unsupported
- All development focuses on the Heft toolchain
Customization options
The new toolchain provides three levels of customization.
Standard customization
For most scenarios, you can modify Heft configuration files to adjust build behavior, create custom Heft plugins for project-specific tasks, and extend or override the default SPFx rig configuration.
Advanced customization
For webpack modifications, Heft’s plugin model lets you programmatically access and modify webpack configurations while maintaining compatibility with the broader webpack ecosystem.
In addition, you can create your own Heft plugins for reusable tasks.
Full control through ejection
For developers requiring complete control, an “eject” option provides a standalone webpack.config.js file. You get full webpack control while still using Heft for task orchestration. However, you should only consider this as an option of absolute last resort. This is a one-way operation that you can’t easily revert from. Ejecting the webpack configuration means you are taking full responsibility of the build toolchain going forward with your project. This also means you won’t receive any future improvements to the toolchain in future SPFx releases.
Stay tuned for articles over the next two days where I’ll go deeper how to implement your build toolchain customizations, so I won’t go into depth here. Stay tuned for those articles.
Migrating existing projects
If you have existing SPFx projects, you have options. 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 primarily affects newly generated projects and those that choose to migrate.
I wrote the official migration guide for Microsoft’s documentation. If you’re ready to migrate your existing projects to the new Heft-based toolchain, check out the Migrate from the Gulp-based Toolchain to the Heft-based Toolchain article for detailed instructions.
Learn more about the SPFx toolchain
The Heft-based toolchain opens up powerful customization options for SPFx developers. Understanding how to create custom plugins is just one piece of the puzzle.
I’m running a hands-on SPFx workshop in January that covers the build toolchain in depth. You’ll learn not just the “how” but the “why” behind these tools—the kind of understanding that helps you solve problems on your own.
Learn more and enroll in the workshop: Learn SharePoint Framework Development - January 13-22, 2026.
I’m updating my Mastering the SharePoint Framework course with comprehensive coverage of the new toolchain. Stay tuned for those updates!
Conclusion
The SPFx v1.22 represents a significant investment in the framework’s long-term health. The clean npm audits alone remove a major friction point for enterprise adoption. TypeScript v5.8 brings modern language features. And the Heft-based toolchain, while requiring a learning curve, provides a more sustainable foundation for customization.
If you’re starting new projects, embrace the new toolchain. If you have existing projects, take your time with migration since gulp continues working through the SPFx v1.23.
What do you think about these changes? Are you planning to migrate your existing projects to the new toolchain, or will you wait until gulp support ends? Drop a comment below and let me know your migration strategy.
Microsoft MVP, Full-Stack Developer & Chief Course Artisan - Voitanos LLC.
Andrew Connell is a full stack developer who focuses on Microsoft Azure & Microsoft 365. He’s a 21-year recipient of Microsoft’s MVP award and has helped thousands of developers through the various courses he’s authored & taught. Whether it’s an introduction to the entire ecosystem, or a deep dive into a specific software, his resources, tools, and support help web developers become experts in the Microsoft 365 ecosystem, so they can become irreplaceable in their organization.
