SPFx-Framework v1.22 - Rush Stack, Heft & Webpack-based toolchain - First try
The new SPFx-Framework v1.22, which is currently available as BETA 5, introduces a new toolchain based on Heft. Older versions of the SPFx framework use a Gulp & Webpack-based toolchain. However, this Gulp & Webpack-based toolchain has several significant issues. Furthermore, the change to Heft aligned Microsoft's internal development practices with those of external developers, due to the fact that Microsoft already uses Heft as the toolchain for SPFX. The new refreshed toolchain contains the following tools: Rush Stack, Heft & Webpack.
In short, these tools are responsible for performing specific tasks:
Rush Stack:
At its core is Rush, a scalable monorepo build orchestrator that ensures deterministic package installations and builds projects in the correct order as quickly as possible.
Heft:
Heft is a config-driven toolchain that invokes other popular tools like TypeScript, ESLint, Jest, Webpack, and API Extractor to build web applications, Node.js services, command-line tools, and libraries. It's designed for use in monorepos with potentially hundreds of projects.
You can read more about all the reasons for moving to Heft in the official Microsoft learning article: SharePoint Framework Toolchain: Rush Stack, Heft, & Webpack
The impact of the new toolchain
BUT WAIT:
The following important question comes up immediately: "Is it necessary to migrate all existing SPFx-Framework solutions to the new toolchain? How is the impact on existing solutions?"
Short answer: No impact at the moment 😊
You can use v1.22 with existing projects and with the old gulp-toolchain appoach.Yeahhh :-)
... Importantly, existing projects that upgrade to v1.22 can continue using their current gulp-based builds without modification. and ...SharePoint Framework Yeoman generator ... provides a command-line option to use the legacy gulp toolchain insteadAnnouncement SPFx version 1.22
This means that you can create new projects with v1.22 and you can still use the old-fashioned toolchain. Existing projects are not affected at all. But in case you create a new project, I would recommend starting to use the new toolchain instead of sticking to the gulp-based toolchain.
But consider the release roadmap because the official Gulp support is going to end with release v1.24 - see below.
What is the plan for upcoming SPFx-Releases?
Regarding the roadmap starting with SPFx v1.23, new projects will exclusively support Heft. But if the SPFx CLI isn't fully prepared by this release, the generator from v1.22 will continue with its existing support model. Developers with existing projects will still be able to use gulp-based builds in v1.23.
Release v1.24 and later
Starting with SPFx v1.24, while existing projects may still technically continue using gulp-based builds, the gulp toolchain will become officially unsupported.
Give it a try
I decided to do a test, and I want to test the new developer experience with this new toolchain approach. In this article, I am going to show you how to install and use the new SharePoint SPFx Framework on a new machine.
As usual, an SPFx-Framework development environment needs some prerequisites installed. I did my test on a fresh, new Hyper-V-based Windows 11 machine. At first I thought to use Docker, but I decided to use a VM to prevent possible negative side effects during my first tests.
The first thing I did was install my new machine. After I have installed my new fresh machine, I checked the SPFx-Release version requirements on the compatibility page: SharePoint Framework development tools and libraries compatibility. The SPF-Framework needs the following versions:
- Node.js: v22 (LTS)
- TypeScript: 5.8
- React: v17.0.1
So, I have downloaded Node.JS from here and installed the v22 version on the machine. After this I installed VS-Code because it's recommended to use a development IDE. Then I installed the latest version of the Yeoman generator using the command line: npm install yo --global
In prior SPFx versions you have to install Gulp and then you must trust the development certificate. These steps are obsolete now due to the fact that we use Heft. To install the latest SPFx-Framework use the following npm command: npm install @microsoft/generator-sharepoint@next --global
Then it is possible to create a new SPFx based solution. For this execute the command: yo @microsoft/sharepoint to start the Yeoman generator. The generator starts as usual with a welcome screen as you can see below.
 |
| Welcome to a new project |
For this example I have used a WebPart to test out the new toolchain structure. You can see all my decision for the new project in the screenshot:
 |
| Project settings |
After the project has been created, it can be tested. Just edit the serve.json file inside the config folder before and set the initialPage to an existing SharePoint site. To start the project run the command: npm run start
If you encounter the following problem and see an error message stating "npm.ps1 cannot be loaded because running scripts is disabled on this system" you must adjust the PowerShell execution policy, because the error indicates that the PowerShell execution policy is preventing the npm.ps1 script from running.
 |
| Error regarding PowerShell execution policy |
To resolve this, the PowerShell execution policy needs to be adjusted. Just execute the following command: Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
To verify the setting you can use the command: Get-ExecutionPolicy -List
After the projects start a message comes up to accept and install the rushstack-certificate-manager because, as I wrote, Rush is used within the toolchain.
 |
| Install certificate |
After accepting this message with "Yes," the building process continues, and after this you can load your SharePoint workbench. Then a warning appears regarding the external scripts.
 |
| Allow scripts on developer workbench / SharePoint test page |
After you have accepted this warning, you can add the WebPart to the workbench.
Project changes
Compared to the Gulp-based SPFx solution, the overall project structure has not changed much. Due to the new tools (Heft, Rush, etc.), some new config files exist, and some "old" config files disappeared. The screenshot below shows on the left side an SPFx v1.22 project and on the right side a v1.21 SPFx solution structure.
 |
| Compare project structure and config files |
As you can see, the gulpfile.js is no longer present in v1.22. However, you can also see that the overall structure of the project remains unchanged, as the changes in the toolchain only affect how the app is ultimately built. Inside the config folder, there are two new files called rig.json and typescript.json. The purpose of the rig.json file is to tell a project to inherit its configuration from a shared "rig" package, rather than defining its own. This allows multiple projects to share a common build setup, minimizing configuration duplication and ensuring consistency across a large monorepo or a group of related projects. In summary, this approach means that you can centralize your shared config files for multiple projects. The typescript.json uses such a shared configuration technique and extends the common typescript.json files, as demonstrated by the below example.
{ "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"] } }
In summary, the new toolchain feels easier to use, and the opportunity to centralize the config files for multiple projects to share the same config settings makes the project setting management much easier.
The main reason for shifting the toolchain is regarding the release notes:
... focuses updating and modernizing the build toolchain and to address all known 'npm audit' reported vulnerabilities in the Yeoman package and in the scaffolded projects.
Below you see the npm audit report output result from a new SPFx v1.22 and from a new SPFx v1.21.1 project. As you can notice, there are no serious vulnerabilities in an SPFx v1.22 (Beta 5) project👍.
|
| Compare npm audit report |
Kommentare