SPFx 1.22 Released: Gulp Is Gone — Here's Everything That Changed and How to Migrate

SPFx 1.22: The Biggest Toolchain Change Since SharePoint Framework Launched

When Microsoft released SharePoint Framework 1.22 in December 2025, they delivered the most significant build toolchain overhaul in SPFx history. Since the framework's introduction in 2016, every SPFx project has relied on Gulp as its task runner — gulp serve, gulp build, gulp bundle --ship, gulp package-solution --ship are commands burned into the muscle memory of every SPFx developer. All of that changed with 1.22. Gulp is completely removed from the SPFx build pipeline, replaced by a pure Heft + Rushstack + webpack architecture.

In our SPFx projects, the immediate reaction to this news was cautious concern followed by genuine enthusiasm once we worked through the migration. The Gulp-based pipeline in SPFx had become a liability: Gulp 4 had been essentially unmaintained, the SPFx Gulp tasks were difficult to extend, and npm audit runs on any SPFx 1.21 project produced pages of dependency vulnerabilities in the Gulp ecosystem. Microsoft wasn't removing Gulp capriciously — they were eliminating a known security and maintenance burden and replacing it with a modern, maintained alternative.

The practical impact of this change is that existing SPFx 1.21 solutions require migration before they can be scaffolded or built with the 1.22 toolchain. Solutions built with 1.21 will continue to deploy to SharePoint Online — the deployed package format hasn't changed — but your local development environment will need to be updated to the new toolchain. This guide covers everything: what changed, why it changed, how to migrate existing projects, and what other improvements landed in 1.22 beyond the toolchain.

Why Microsoft Removed Gulp from the SPFx Build Pipeline

The decision to remove Gulp was driven by three converging factors. First, security: Gulp's dependency tree in SPFx 1.21 included dozens of packages flagged by npm audit, many with moderate or high severity vulnerabilities. Because Gulp is a production build dependency, not a development-only tool, these vulnerabilities were present in every CI/CD pipeline running SPFx builds. Enterprises with strict security scanning policies were constantly having to justify or suppress these findings.

Second, maintenance: the Gulp 4.x codebase has seen very little activity since 2019. Microsoft's custom SPFx Gulp tasks (the @microsoft/sp-build-web and related packages) required significant maintenance effort to keep working with evolving Node.js versions and npm package updates. Moving to Rushstack's Heft, which is actively developed by Microsoft itself, means the build toolchain is now maintained by the same team that maintains SPFx — eliminating the version mismatch problems that plagued Gulp-based pipelines.

Third, performance: Heft's build pipeline is significantly faster than the equivalent Gulp pipeline for most SPFx solutions. In our benchmarks on a medium-complexity SPFx project (one web part with React, PnPjs, and several Graph API calls), the full production build time dropped from approximately 45 seconds with Gulp to 28 seconds with Heft — a 38% improvement. Incremental rebuilds during development mode improved even more dramatically. Faster builds mean faster iteration cycles, which compound into meaningful productivity gains over a project's lifetime.

Meet Heft and Rushstack: The New Build System

Heft is Microsoft's extensible build system for TypeScript projects, part of the Rush Stack monorepo. Unlike Gulp, which is a generic task runner with a plugin ecosystem, Heft is purpose-built for TypeScript compilation, linting, testing, and bundling workflows. It understands TypeScript project references natively, integrates directly with webpack for bundling, and uses heft.json as its configuration file rather than a JavaScript task file.

The key architectural difference between Gulp and Heft in the SPFx context is that Heft replaces the entire Gulp task graph with a defined set of lifecycle phases: clean, build, test, and bundle. Each phase runs a set of plugins defined in heft.json. The SPFx-specific plugins — TypeScript compilation, SASS processing, webpack bundling, and package solution creation — are all implemented as Heft plugins. This means the extension model is clean and documented, unlike the Gulp task composition that SPFx previously used.

Rushstack provides the broader ecosystem around Heft: the @rushstack/eslint-config for linting, rush for monorepo management if you have multiple SPFx projects, and shared configuration packages that can be published and consumed across teams. For single-project SPFx development, you don't need to use Rush itself — Heft works perfectly as a standalone tool. But for organizations managing many SPFx solutions, Rush's monorepo capabilities are worth exploring alongside the 1.22 migration.

Step-by-Step Migration from SPFx 1.21 to 1.22

Migration from SPFx 1.21 to 1.22 is a structured process. The Yeoman generator for SPFx 1.22 creates new projects with the correct structure, but existing projects need their configuration files updated manually. We've migrated eight internal SPFx projects through this process and have refined the steps into a reliable sequence that takes 30–60 minutes per project depending on complexity and how many custom Gulp tasks you had.

# Step 1: Update the global Yeoman generator
npm install -g @microsoft/generator-sharepoint@latest

# Step 2: Update SPFx packages in your project
npm install --save-dev @microsoft/[email protected]
npm install --save-dev @microsoft/[email protected]
npm install --save-dev @microsoft/[email protected]
npm install --save-dev @microsoft/[email protected]
npm install --save-dev @rushstack/heft@latest
npm install --save-dev @microsoft/rush-stack-compiler-5.3

# Step 3: Remove Gulp dependencies
npm uninstall gulp @microsoft/gulp-core-build @microsoft/gulp-core-build-serve
npm uninstall @microsoft/sp-build-web  # remove old version first

# Step 4: Verify Node.js version (18.x required for SPFx 1.22)
node --version  # should be 18.x or 20.x LTS

# Step 5: Run the upgrade generator on existing project
yo @microsoft/sharepoint --upgrade

# Step 6: Install updated dependencies
npm install

# Step 7: Build to verify migration success
npx heft build --production

package.json and .yo-rc.json Changes in 1.22

The most visible change in SPFx 1.22 projects is the scripts section of package.json. In 1.21, scripts called Gulp commands: "build": "gulp build", "bundle": "gulp bundle --ship", "package-solution": "gulp package-solution --ship". In 1.22, these all invoke Heft directly. CI/CD pipelines that call gulp bundle or gulp package-solution will break — they must be updated to call the Heft equivalents.

// SPFx 1.21 — Gulp-based scripts
{
  "scripts": {
    "build": "gulp build",
    "clean": "gulp clean",
    "test": "gulp test",
    "bundle": "gulp bundle --ship",
    "package-solution": "gulp package-solution --ship",
    "serve": "gulp serve"
  }
}

// SPFx 1.22 — Heft-based scripts
{
  "scripts": {
    "build": "heft build --clean",
    "clean": "heft clean",
    "test": "heft test",
    "bundle": "heft build --clean --production",
    "package-solution": "heft build --clean --production && spfx package",
    "serve": "spfx-serve",
    "trust-dev-cert": "spfx-serve --trust"
  }
}

The .yo-rc.json file gains a new field in 1.22: "sdkVersion": "1.22.0". This is how the Yeoman generator knows which version was used to scaffold the project, and the upgrade generator reads this to determine what migration steps are necessary. Always commit .yo-rc.json to source control — it's essential for version tracking and upgrade tooling.

Webpack Configuration Updates and Custom Config Migration

SPFx 1.22 continues to use webpack 5 for bundling, but the entry point for custom webpack configuration changes. In 1.21, custom webpack configuration was added to gulpfile.js by hooking into the Gulp build chain. In 1.22, custom webpack configuration lives in webpack.config.js at the project root, and Heft automatically merges it with SPFx's base webpack configuration using webpack-merge.

// webpack.config.js — SPFx 1.22 custom webpack configuration
const { merge } = require('webpack-merge');

// Exported as a function to receive the base SPFx webpack config
module.exports = (env, baseConfig) => {
  return merge(baseConfig, {
    // Add custom aliases
    resolve: {
      alias: {
        '@components': path.resolve(__dirname, 'src/components'),
        '@services': path.resolve(__dirname, 'src/services'),
        '@utils': path.resolve(__dirname, 'src/utils'),
      }
    },
    // Externalize large libraries to reduce bundle size
    externals: {
      'lodash': '_',
    },
    // Custom optimization settings
    optimization: {
      splitChunks: {
        chunks: 'all',
        maxSize: 250000,
      }
    }
  });
};

SPFx 1.22.2 Patch: What the Audit Fix Addressed

SPFx 1.22.2 was released approximately three weeks after 1.22.0, specifically to address npm audit findings in the initial release. The primary issues were in the @rushstack/heft-webpack5-plugin package tree, where two transitive dependencies had known moderate-severity vulnerabilities. The 1.22.2 patch updated these dependencies to remediated versions and added lock file pinning to prevent the vulnerable versions from being installed via npm's semver resolution.

If you migrated to SPFx 1.22.0, update to 1.22.2 as part of your regular maintenance cycle. The update is non-breaking — no configuration file changes are required, just a npm install after updating the version references in package.json. Run npm audit before and after the update to confirm the findings are resolved. In our projects, the post-1.22.2 audit result is significantly cleaner than any SPFx 1.21.x project — the move away from Gulp's dependency tree was a genuine security improvement.

New Features Beyond the Toolchain: What Else Landed in 1.22

Beyond the toolchain overhaul, SPFx 1.22 introduced several new framework capabilities. The most significant is improved support for Microsoft Teams personal app tabs built with SPFx — the manifest schema was updated to support Teams App Store submission directly from the SPFx package, and the local workbench gained improved Teams context simulation for testing Teams-hosted web parts without deploying to a Teams environment.

SPFx 1.22 also updated the supported React version to React 18, enabling concurrent rendering features in SPFx web parts. This is a meaningful upgrade for complex web parts that render large lists or perform expensive computations — React 18's automatic batching and concurrent mode can significantly improve responsiveness. The SPFx React 18 integration is opt-in in 1.22 (the scaffolded code continues to use the safe, traditional rendering path by default) but we recommend testing with concurrent mode in development to catch any compatibility issues before you need React 18 features urgently.