SPFx 1.22 -- The Biggest SharePoint Framework Update in Years

I just scaffolded my first SPFx 1.22 project. No gulpfile.js. No npm audit warnings. TypeScript 5.8 out of the box. After years of the same foundation, this release actually feels different.

SPFx 1.22 went GA on December 10, 2025, and the toolchain got its first serious overhaul since 2016. The headline: Gulp is out, Heft is in. But there’s more going on under the hood than just swapping one build orchestrator for another.

What actually changed

Three things matter in this release. Everything else is downstream of these.

1. Gulp is replaced by Heft as the build orchestrator. Gulp served SPFx well for six years, but the custom gulp-core-build stack had become unmaintained, riddled with outdated dependencies, and difficult to extend. Heft is a config-driven toolchain from the Rush Stack ecosystem that Microsoft already uses internally. Webpack still does the actual bundling underneath – Heft just orchestrates the build process.

2. TypeScript 5.8 is the new default. New projects scaffolded with the 1.22 generator use TypeScript v5.8 right away. No more manually upgrading TypeScript and hoping nothing breaks.

3. Zero npm audit vulnerabilities. This is the one that made me smile. Run npm audit on a freshly scaffolded 1.22 project and you get a clean report. After years of ignoring dozens of audit warnings in every SPFx project, that alone makes the upgrade worth it.

Creating your first SPFx 1.22 project

Before you start, make sure you have Node.js v22 LTS installed. SPFx 1.22 requires Node 22 – earlier versions like Node 18 or Node 20 won’t work.

Install the latest generator:

npm install @microsoft/generator-sharepoint@latest --global

Scaffold a new project:

yo @microsoft/sharepoint

The Yeoman generator walks you through the same prompts as before – solution name, web part or extension, React or no React. Nothing new there. But the output is where things get interesting.

The new project structure

Open your freshly scaffolded project and the first thing you’ll notice: there is no gulpfile.js. Instead, you’ll find new config files in the config/ directory.

Here is what changed:

config/rig.json

This is the most important new file. It tells your project to inherit its entire build configuration from a shared “rig” package:

{
  "$schema": "https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json",
  "rigPackageName": "@microsoft/spfx-web-build-rig"
}

That single line – rigPackageName – points to an npm package that contains the complete SPFx build definition. Phases, tasks, webpack configuration, TypeScript settings – it’s all defined in the rig. Your project just references it. This means less config clutter in your repo and a single source of truth for the build pipeline.

config/sass.json

This file extends the default Sass configuration from the rig:

{
  "$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"
}

If you need to customize Sass processing (for example, restricting file extensions), you override properties in this file rather than writing custom Gulp tasks.

No local heft.json

You might expect a config/heft.json in your project. You won’t find one. The rig package contains the heft.json with all the phase and task definitions. Your project inherits everything from @microsoft/spfx-web-build-rig unless you explicitly override it.

The new build commands

This is the part that will affect your muscle memory. The npm scripts in package.json now call Heft instead of Gulp.

Here is the mapping from old to new:

A few things to watch out for:

• --ship is now --production. Everywhere. You’ll forget this at least once.
• Build and bundle are combined. Heft doesn’t have a separate bundle command – heft build compiles and bundles in one step.
• heft start replaces gulp serve. Same result, different command.
• There is a new heft dev-deploy command that deploys your built assets to a testing CDN so you can validate how your component loads from an external source. Gulp didn’t have anything like this.

Your typical development workflow becomes:

# Install dependencies
npm install

# Start local workbench
heft start

# Production build and package
heft build --production
heft package-solution --production

Or if you prefer using the npm scripts from package.json:

npm run build
npm start

What stays the same

Not everything changed, and that’s worth mentioning.

Webpack is still the bundler – Heft just orchestrates it. React works exactly as before. The src/ folder structure is identical, web parts and extensions live in the same places, and the config/ folder still has package-solution.json, serve.json, and the rest. The .sppkg output is the same format too, so your CI/CD pipeline only needs updated build commands, not a rewrite. The Yeoman generator prompts haven’t changed either.

If you know SPFx, you already know SPFx 1.22. The conceptual model hasn’t changed. Only the build plumbing underneath is different.

Common gotchas and troubleshooting

I’ve been working with 1.22 since it dropped, and a few things tripped me up. I’ve also seen others hit these.

Node.js version matters

SPFx 1.22 requires Node.js v22 LTS. If you’re still on Node 18 or 20, you’ll need to upgrade. I recommend using nvm to manage multiple Node versions if you’re also maintaining older SPFx projects:

nvm install 22
nvm use 22
node --version  # should show v22.x.x

Muscle memory: –ship vs –production

You’ll type --ship out of habit. I did, several times. It won’t work. The Heft equivalent is --production. If your build looks like it’s not minifying or optimizing, double-check this flag.

Custom Gulp tasks won’t carry over

If you had custom tasks in your gulpfile.js – file copying, code generation, version stamping – those need to be migrated. The Heft equivalent is either a Heft plugin or the Heft Run Script plugin, which lets you execute arbitrary JavaScript during a build phase. According to Microsoft, you should be able to move your existing customizations over with config changes and some code relocation, not a full rewrite.

SCSS module handling

The Heft toolchain treats .scss files as CSS Modules by default. Files ending in .global.scss are treated as global styles. This is actually more explicit and predictable than the old behavior, but it can catch you off guard if you’ve got SCSS files that relied on implicit global scoping.

Bundle size differences

Some early adopters reported that .sppkg bundle sizes were larger compared to 1.21.1 builds during the beta phase. This was addressed in later patches, but keep an eye on your bundle sizes after upgrading and compare them to your previous builds.

The legacy escape hatch

If you really need Gulp for a new project (maybe a quick prototype while you learn Heft), the generator still supports it:

yo @microsoft/sharepoint --use-gulp

This scaffolds a project with the old Gulp-based toolchain. But know that this is temporary – starting with SPFx 1.23, new projects will default to Heft only, and by 1.24, the Gulp toolchain becomes officially unsupported.

Should you upgrade existing projects now?

It depends on where you are.

For new projects, just use 1.22. There’s no reason to start on the old toolchain when you get TypeScript 5.8, zero audit warnings, and Heft out of the box.

If you have existing projects with no custom Gulp tasks, you can upgrade your package.json dependencies to 1.22 and keep using Gulp for now. Your existing build won’t break. Plan the Heft migration for a maintenance window when you have time to test properly.

If you have existing projects with custom Gulp tasks, I would wait. Figure out what those custom tasks actually do, check whether Heft plugins or the Run Script plugin can replace them, and migrate piece by piece. Microsoft has published a dedicated migration guide that walks through the process.

The support timeline gives you runway. Gulp works in 1.22 and 1.23. It becomes unsupported in 1.24. You have time, but don’t ignore it.

What I think this means longer term

Microsoft is bringing the external developer toolchain in line with what they use internally. That’s a good sign. It usually means the tooling gets maintained instead of rotting.

The Heft move also makes things possible that were painful before – proper monorepo support, shared build configs across projects, and a plugin ecosystem that doesn’t depend on an abandoned Gulp stack. I’m curious to see how much of that actually ships in 1.23 and 1.24.

For now, install the generator, scaffold a project, and poke around. The Heft commands will feel unfamiliar for a week and then you’ll wonder why it took this long.

Read more

• SPFx 1.22 GA Announcement – Microsoft 365 Dev Blog – the official announcement covering the Heft switch, TypeScript 5.8, and npm audit improvements
• SPFx 1.22 Release Notes – Microsoft Learn – full release notes with breaking changes and feature details
• Heft-based Toolchain Overview – Microsoft Learn – how Heft fits into the SPFx build pipeline
• Understanding the Heft-based Toolchain – Microsoft Learn – deeper dive into customizing Heft for your projects
• Migrate from Gulp to Heft Toolchain – Microsoft Learn – step-by-step migration guide for existing projects
• Heft Official Documentation – Rush Stack – the upstream Heft docs covering plugins, rigs, and the full config model