Migrate SPFx from Gulp to Heft & Webpack (2026)

The Biggest SPFx Toolchain Change in Years

March 2026 marks a turning point for SharePoint Framework developers. Two major changes are happening simultaneously:

• SPFx 1.22 replaced Gulp with Heft as the build system

• SPFx 1.23 introduces a preview of the new SPFx CLI that replaces the Yeoman generator

If you maintain SPFx projects, you need to understand both changes. This guide covers what changed, why it matters, and exactly how to migrate your existing projects.

What Changed and Why

The Problem with the Old Toolchain

The original SPFx toolchain had accumulated years of technical debt:

Issue	Impact
Gulp dependency chain	50+ npm audit warnings in every new project
Yeoman generator coupling	Generator version locked to SPFx version
Outdated build pipeline	Blocked TypeScript 5.x adoption
Custom gulp tasks	Fragile, undocumented extension points

Microsoft addressed all four issues across SPFx 1.22 and 1.23.

Timeline of Changes

Version	Release	Change	Status
SPFx 1.21	September 2025	Last version with Gulp-only toolchain	Stable
SPFx 1.22	December 2025	Heft replaces Gulp (Gulp still available via flag)	Stable
SPFx 1.23	March 2026	New SPFx CLI preview, open-source templates	Preview
SPFx 1.24	June 2026	SPFx CLI general availability	Planned

Change 1: Gulp to Heft (SPFx 1.22+)

What is Heft?

Heft is a build orchestrator from the Rush Stack ecosystem. It replaces Gulp as the task runner but Webpack still handles bundling under the hood. Think of it as a modern wrapper around the same compilation pipeline.

What Changed in Your Project

Before (Gulp)	After (Heft)
gulpfile.js	Removed
gulp serve	npm run serve (calls Heft)
gulp bundle --ship	npm run build (calls Heft)
gulp package-solution --ship	npm run package (calls Heft)
Custom gulp tasks in gulpfile.js	Heft plugins or rig extensions

New Configuration Files

SPFx 1.22 projects include several new files in the ./config folder:

config/rig.json — References the shared SPFx build configuration:

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

config/sass.json — Sass plugin configuration:

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

The rig system means most configuration lives in the shared @microsoft/spfx-web-build-rig package rather than in your project. This keeps your project clean and makes future upgrades easier.

Step-by-Step: Migrate an Existing Project to Heft

Follow these steps to migrate an SPFx 1.21 project to the Heft-based toolchain:

Step 1: Update SPFx Dependencies

Update your package.json to reference SPFx 1.22 packages. The CLI for Microsoft 365 can generate the exact changes needed:

npx @pnp/cli-microsoft365 spfx project upgrade
--toVersion 1.22.0 --output md

This outputs a markdown report with every dependency change required.

Step 2: Remove Gulp Dependencies

Uninstall the Gulp packages that are no longer needed:

npm uninstall gulp @microsoft/sp-build-web
@microsoft/sp-module-interfaces

Step 3: Install Heft Dependencies

npm install @rushstack/heft @microsoft/spfx-web-build-rig
--save-dev

Step 4: Update npm Scripts

Replace the gulp commands in your package.json:

{
"scripts": {
"build": "heft build --clean",
"bundle": "heft build --clean",
"serve": "heft build --watch",
"package": "heft build --clean
&& node ./node_modules/@pnp/spfx-controls-react/node_modules/.bin/package-solution"
}
}

Note: The exact scripts may vary. Check the scripts generated by a fresh SPFx 1.22 project for the most current commands.

Step 5: Add Configuration Files

Create the rig.json and sass.json files in your ./config directory as shown above.

Step 6: Delete gulpfile.js

Remove the gulpfile.js from your project root. If you had custom gulp tasks, see the "Migrating Custom Gulp Tasks" section below.

Step 7: Test the Build

npm run build

If the build succeeds, your migration is complete. Run npm run serve to verify the local development experience works as expected.

Migrating Custom Gulp Tasks

If you had custom logic in gulpfile.js (such as custom bundling steps or environment variable injection), you have three options:

Approach	Complexity	Best For
Heft plugins	Medium	Reusable build steps shared across projects
Pre/post npm scripts	Low	Simple one-off commands
Rig ejection	High	Full control over the entire build pipeline

The simplest migration path for most custom gulp tasks is to convert them to npm scripts:

{
"scripts": {
"prebuild": "node ./scripts/inject-env-vars.js",
"build": "heft build --clean"
}
}

For complex scenarios, you can create a custom Heft plugin. This is more involved but provides a cleaner, more maintainable extension point than custom gulp tasks ever did.

Change 2: New SPFx CLI (SPFx 1.23+)

What is the New SPFx CLI?

The Yeoman generator (yo @microsoft/sharepoint) is being replaced by a standalone SPFx CLI. Key differences:

Feature	Yeoman Generator	New SPFx CLI
Installation	npm install -g yo @microsoft/generator-sharepoint	Standalone CLI (npm package)
Version coupling	Locked to SPFx version	Decoupled from SPFx versions
Templates	Bundled in generator	Open-source on GitHub
Customization	Limited	Company-specific templates supported
Status in 1.23	Still available	Preview
Status in 1.24	Deprecated	General Availability

Why This Matters

The decoupling is the biggest win. Today, you install a specific version of the Yeoman generator to scaffold a specific version of SPFx. With the new CLI, you install it once and it can scaffold any supported SPFx version.

The open-source templates mean your organization can create standardized project templates with your preferred libraries, folder structure, and configurations baked in.

Using the New SPFx CLI (Preview)

As of SPFx 1.23, the CLI is in preview. To try it:

npm install -g @microsoft/spfx-cli@preview

Then create a new project:

spfx new --solution-name my-webpart --component-type webpart
--framework react

Important: The exact commands may evolve before the 1.24 GA release. Check the official SPFx documentation for current syntax.

Decision Matrix: When Should You Migrate?

Not every project needs to migrate immediately. Use this matrix:

Scenario	Recommendation
Starting a brand new SPFx project	Use SPFx 1.23 with Heft (skip Gulp entirely)
Active project on SPFx 1.21	Migrate to 1.22 Heft when you have a sprint for tech debt
Legacy project in maintenance mode	Stay on current version until a feature update is needed
Project with heavy custom gulp tasks	Plan migration carefully — test custom logic conversion first
CI/CD pipelines using gulp commands	Update pipeline scripts when migrating to Heft

The key deadline: Gulp support will eventually be removed. Microsoft has not announced a hard deprecation date, but SPFx 1.22 already defaults to Heft, and the trend is clear. Plan your migration in 2026 rather than being forced into it later.

CI/CD Pipeline Updates

If your DevOps pipelines use gulp commands, update them when migrating:

Before (Gulp-based pipeline):

- script: gulp bundle --ship
- script: gulp package-solution --ship

After (Heft-based pipeline):

- script: npm run build
- script: npm run package

Both Azure DevOps and GitHub Actions pipelines need this update. The npm scripts abstract the underlying tool, so future toolchain changes will not require pipeline updates.

What About the CLI for Microsoft 365?

The CLI for Microsoft 365 remains your best friend for project upgrades. Its spfx project upgrade command generates a detailed migration report:

npx @pnp/cli-microsoft365 spfx project upgrade
--toVersion 1.23.0 --output md

This tool does not modify your files automatically. Instead, it produces a step-by-step guide specific to your project, listing every dependency change, configuration update, and potential breaking change.

What Else Is New in SPFx 1.23

Beyond the CLI preview, SPFx 1.23 includes:

• Open-source solution templates — Project scaffolding templates are now on GitHub, enabling community contributions

• TypeScript 5.8 — Continued from SPFx 1.22, bringing modern language features like using declarations

• Clean npm audits — Zero audit warnings in new projects (a huge win for enterprise compliance)

• Navigation Customizers preview — Override top and side navigation elements (GA in 1.24)

For building web parts with these new tools, see my SPFx web part complete guide. To leverage SPFx with Microsoft Graph, check out 10 practical Graph API examples.

Frequently Asked Questions

Q: Do I have to migrate to Heft immediately?

No. SPFx 1.22 includes a --use-gulp flag for the Yeoman generator that creates projects with the legacy Gulp toolchain. Existing projects on older SPFx versions continue to work without changes. However, new features and security patches will only come to the Heft-based toolchain going forward.

Q: Will my existing SPFx web parts break?

No. The toolchain change affects how you build and serve your project, not how it runs in SharePoint. Your deployed .sppkg files work the same regardless of whether they were built with Gulp or Heft.

Q: Can I use the new SPFx CLI in production today?

The CLI is in preview with SPFx 1.23. For production projects, continue using the Yeoman generator until the CLI reaches GA with SPFx 1.24 (June 2026). Test the CLI with side projects to familiarize yourself with the new workflow.

Q: What happened to the local workbench?

The local workbench (/temp/workbench.html) has been deprecated in favor of in-page debugging directly on SharePoint Online. This provides a more accurate testing environment since your web parts run in the real SharePoint context. Use npm run serve and navigate to your SharePoint site with ?debugManifestsFile=... in the URL.

Q: How do I handle custom gulp tasks for environment-specific builds?

Convert simple tasks to npm pre and post scripts. For complex build customizations, create a custom Heft plugin. See the Heft plugin documentation for patterns and examples.

What to Do Next

• Audit your current SPFx projects — List all projects and their current SPFx version

• Try the Heft toolchain — Scaffold a new SPFx 1.22+ project and compare the dev experience

• Test the CLI preview — Install the preview CLI and scaffold a test project

• Update CI/CD pipelines — Replace gulp commands with npm scripts when you migrate

• Plan your migration timeline — Use the decision matrix above to prioritize

For more SharePoint development guides, explore my articles on building Viva Connections ACEs, Power Automate document workflows, and Copilot Studio AI assistants.

Visualize Your Upgraded Architecture

As you migrate your SPFx projects, it is critical to document your target environment. Use the free M365 Architecture Canvas to drag and drop SharePoint and Teams components into a visually exportable architecture diagram.