Migrate your existing SPFx solution to the new HEFT-based toolchain.

New SPFx-apps solutions should use the latest SharePoint Framework version. The latest SPFx version (1.22.* blog from 22.02.2026) introduced a new toolchain based on HEFT instead of Gulp (see my blog post: SPFx-Framework v1.22 - Rush Stack, Heft & Webpack-based toolchain - First try). This means that existing projects must migrate the typical SPFx libraries, and in addition, the toolchain also needs to be updated. The migration path is explained in the Microsoft learn article:
Migrate from the Gulp-based to the Heft-based Toolchain

In the following blog post I describe my steps and experience with the migration process. For this demonstration, I've migrated an existing SPFx web part from 1.21.1 to 1.22.

At first I checked if I had installed the SPFx 1.22 version already. I did this with:

npm ls -g --depth=0

After I verified that the new version is available, I continued with the first step regarding the official documentation. I uninstalled the Gulp toolchain dependencies with:

npm uninstall @microsoft/sp-build-web ajv gulp

This gave me the following result:

@microsoft/sp-build-web ajv gulp

Then the rush-stack-compiler-* must be removed. The concrete rush-stack-compiler-* version depends on the TypeScript version. For this project I used TypeScript 5.9.2. To verify the correct version to remove, just check your package.json. In my case I had installed:

@microsoft/rush-stack-compiler-5.3

So I run:

npm uninstall @microsoft/rush-stack-compiler-5.3

uninstall rush-stack-compiler-5.3

Installation of HEFT

After the old dependencies are removed, the new HEFT toolchain can be added to the project. For this run the following command:

npm install @microsoft/spfx-web-build-rig@1.22.1 \
            @microsoft/spfx-heft-plugins@1.22.1 \
            @microsoft/eslint-config-spfx@1.22.1 \
            @microsoft/eslint-plugin-spfx@1.22.1 \
            @microsoft/sp-module-interfaces@1.22.1 \
            @rushstack/eslint-config@4.5.2 \
            @rushstack/heft@1.1.2 \
            @types/heft-jest@1.0.2 \
            @typescript-eslint/parser@8.46.2 \
            --save-dev --save-exact --force

If you want, you can upgrade to a new TypeScript version, too. But in my case, I already had a new version installed, so I skipped this step.

Now it is time to update the ESLint configuration file. We must add the following two lines after:

'@rushstack/hoist-jest-mock': 1,

INSERT:

'@rushstack/import-requires-chunk-name': 1,
'@rushstack/pair-react-dom-render-unmount': 1,

And we need to delete the following lines from the file:

'@microsoft/spfx/import-requires-chunk-name': 1,
'@microsoft/spfx/pair-react-dom-render-unmount': 1

Don't forget to remove the comma from the previous line :-).

The result should be:

ESLint file after migration

Next stop is the package.json file. Here we need to replace the gulp "scripts" with the new HEFT script:

Existing content:

"scripts": {
    "build": "gulp bundle",
    "clean": "gulp clean",
    "test": "gulp test"
  },

Replace with:

{ 
  "scripts": {
    "build": "heft build --clean",
    "clean": "heft clean",
    "test": "heft test"
  } 
}

The default template for SPFx 1.22 projects contains some additional scripts entries. So, I added these and the final result looks like:

"scripts": {
    "build": "heft test --clean --production && heft package-solution --production",
    "start": "heft start --clean",
    "clean": "heft clean",
    "test": "heft test",
    "eject-webpack": "heft eject-webpack"    
  },

Next, it is important to add a reference to the SPFx build rig. For this a new configuration file must be added inside the folder /config called rig.json. Add these lines to the file:

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

Then we need to add a second file in the folder called typescript.json. Put this in the file:

{
  "extends": "@microsoft/spfx-web-build-rig/profiles/default/config/typescript.json",
  "staticAssetsToCopy": {
    "fileExtensions": [".resx", ".jpg", ".png", ".woff", ".eot", ".ttf", ".svg", ".gif"],
    "includeGlobs": ["webparts/*/loc/*.js"]
 }
}

Then update the Saas configuration file. Open the sass.config file within the config folder and replace the content with the following content:

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

Files in config folder after upgrade

Files in config folder

We need to advise TypeScript to use the HEFT configuration for TypeScript. For this the tsconfig.json file must be updated. Remove everything in the file and put only the following instruction:

{
  "extends": "./node_modules/@microsoft/spfx-web-build-rig/profiles/default/tsconfig-base.json"
}

Finally, delete the gulpfile.js!

Now, the SharePoint Framework must be migrated. Run this npm command:

npm install @microsoft/sp-component-base@1.22.1 \
            @microsoft/sp-core-library@1.22.1 \
            @microsoft/sp-lodash-subset@1.22.1 \
            @microsoft/sp-office-ui-fabric-core@1.22.1 \
            @microsoft/sp-property-pane@1.22.1 \
            @microsoft/sp-webpart-base@1.22.1 \
            --save-exact

After the installation, the project can be built with "npm run build". Of course, I had some script errors 😒 but after correction, I could build and run the project again with HEFT 😊.

Final result after error corrections