With the release of SharePoint Framework (SPFx) 1.22, Microsoft introduced a new build chain. This version brings so many changes that SPFx 1.22 feels more like a 2.0 release than a minor update.
You may have heard that the classic gulp/webpack toolchain is being phased out. It’s being replaced by Microsoft’s new build system called Heft: https://heft.rushstack.io
That raises the key question: how can you upgrade your existing SPFx projects to SPFx 1.22 and Heft without breaking anything—especially when you touch an older project for the first time?
TL;DR: This post walks through a reproducible, AI-driven process for upgrading SharePoint Framework (SPFx) projects to SPFx 1.22 and the Heft build chain. At the end, you’ll find a complete copy-paste AI prompt you can use to run the same upgrade flow on any project.
DISCLAIMER If you use spfx-fast-serve it might not work this way. It is oriented to regular SPFx projects
My previous way to upgrade SPFx
I used the M365 CLI to upgrade SPFx a lot:
https://pnp.github.io/cli-microsoft365/cmd/spfx/project/project-upgrade
At the time of writing it only supported 1.22.0 (release candidate 0). Someone will have to update the code to the released version.
I made my workflow more efficient since I got Copilot. I fed the output directly into Copilot, which performed the upgrade for me.
One prompt to upgrade
A manual upgrade doesn’t automatically mean it’s better. Humans make mistakes and can overlook important details. Artificial intelligence also makes errors—but it can often detect and correct its own issues (which is admittedly a bit scary).
To handle the upgrade, I created a prompt and tested it across multiple SPFx projects, including scenarios where several projects coexist in the same repository.
Let’s break it down.
Read the instructions
Microsoft provided information on how to migrate from gulp to heft:
https://learn.microsoft.com/en-us/sharepoint/dev/spfx/toolchain/migrate-gulptoolchain-hefttoolchain
This information can be used to define the upgrade path.
Follow these instructions to upgrade to the latest SPFx version using heft:
https://learn.microsoft.com/en-us/sharepoint/dev/spfx/toolchain/migrate-gulptoolchain-hefttoolchain
By using this first piece of instruction, I tell the AI what I actually want to do. I read the upgrade definition, analyze it, and have a basic understanding of what to do.
Build a safety net
When I use AI, I want to know every risk I am facing after the upgrade. There are many documents in the repo showing how the project has been enhanced. There might be hidden things in there that I don’t know about.
Before you start the migration, perform a risk assessment of the
current solution and document it in a Markdown file.
With this second step, I get a full analysis of the project. Not only that, but I also know what potential issues might be—and before the upgrade I can stop the upgrade process.
In one of my demo projects, it looked like this.
First, it gave me an inventory of the current solution, followed by the risks.
With that, I have a clear understanding of how to deal with the risks.
After acceptance, please proceed
After the risk assessment, the agent allows me to either abort the upgrade or proceed with the following instructions.
Once those risks have been accepted, based on the current branch,
please create a new upgrade branch, follow the instructions, using
only the referenced versions, including optional steps that match my solution,
and normalize all npm scripts to follow best-practice colon notation.
First, Copilot creates a new branch for the upgrade. This avoids damaging my main project branch. If the upgrade fails, I can remove the branch without harm.
The next step is what humans do too: follow the instructions one by one, and let the AI choose which optional steps are required.
The last part of the prompt needs further explanation.
Follow best practice
Here is the part I am talking about.
... normalize all npm scripts to follow best-practice colon notation.
The documentation states the following for the npm scripts.
{
"scripts": {
"test-only": "heft run --only test --",
"deploy": "heft dev-deploy",
"start": "heft start --clean",
"build-watch": "heft build --lite",
"package-solution": "heft package-solution",
"deploy-azure-storage": "heft deploy-azure-storage",
"eject-webpack": "heft eject-webpack",
"trust-dev-cert": "heft trust-dev-cert",
"untrust-dev-cert": "heft untrust-dev-cert"
}
}
The dashes in the script names work, but follow an uncommon pattern and might be hard to read and find when the list gets longer. With that in mind, it is common (and often considered best practice) to use a colon notation, which allows grouping of similar commands.
{
"scripts": {
"build": "heft build --clean",
"build:watch": "heft build --lite",
"build:prod": "heft build --production",
"devcert:trust": "heft trust-dev-cert",
"devcert:untrust": "heft untrust-dev-cert",
"start": "npm run build:watch",
"test": "heft test",
"test:only": "heft run --only test --"
// ...
}
}
With this transformation of the script commands, it is easier to group similar tasks, like all test commands. I can even specify my own custom command—for example a special linter such as stylelint—and a DevOps task. Overall, the scripts are better organised into groups for build, devcert, test, deploy, and so on.
If you want more opinions, I started a discussion of the release candidate version of SPFx:
https://github.com/SharePoint/sp-dev-docs/discussions/10490#discussioncomment-15108245
Some manual changes during the upgrade are needed to organise the scripts, too.
Perform an acceptance test
Before Copilot gives me something that isn’t working, I like to check it myself. Multiple ways could go wrong. For example, the documentation is incomplete; the upgrade was correct, but there are still some unforeseen issues, and so on.
As a final acceptance run, the build command to check for issues:
when there are issues, please provide solutions based on facts.
If everything goes correctly: congratulations, we have an upgraded solution. If not, iterate and fix the issues.
“Based on facts” helps keep the AI from getting too creative when fixing things, and nudges it toward a more evidence-based approach.
We need documentation
The final step is to create proper documentation of everything you did in the solution. This can be used for reference and leaves no surprises if something is not working as expected.
Provide a detailed summary of the applied configuration changes.
In addition to the summary, recommend updates to the documentation
based on issues encountered during the upgrade.
Also, make a recommendation for the Microsoft upgrade guide.
This step is crucial because it gives you a clear indication of what was wrong (maybe before) and what has been fixed during the process.
This part of the prompt is optional because I encountered some minor issues with the Microsoft documentation.
The prompt
With that said, here is the complete prompt to upgrade a SharePoint Framework solution to SPFx 1.22. No tools and no magic—more a process for describing how you want your solutions updated.
Follow these instructions to upgrade to the latest SPFx version using heft:
https://learn.microsoft.com/en-us/sharepoint/dev/spfx/toolchain/migrate-gulptoolchain-hefttoolchain
Before you start the migration, perform a risk assessment of the current solution and document it in a Markdown file.
Once those risks have been accepted, based on the current branch, please create a new upgrade branch, follow the instructions, using only the referenced versions, including optional steps that match my solution, and normalize all npm scripts to follow best-practice colon notation.
As a final acceptance run, the build command to check for issues: when there are issues, please provide solutions based on facts.
Provide a detailed summary of the applied configuration changes.
In addition to the summary, recommend updates to the documentation based on issues encountered during the upgrade.
Also, make a recommendation for the Microsoft upgrade documentation.
The upgrade process
These few instructions provide a reproducible upgrade plan with every precaution in place. I recommend using Claude Sonnet 4 for the upgrade; it yields more reliable results than Copilot.
The overall upgrade follows a 15-step plan and allows user interaction. The overall runtime is a couple of minutes.
It also fixed an ESLint configuration issue that Microsoft hasn’t properly documented. I had to add a manual update after the migration to compare the SPFx package.json dependencies.
The good thing was that I had a minimal and non-extensive ESLint configuration. If you want the full Microsoft ESLint file, you need to copy it from another boilerplate.
Verdict
Overall, the SPFx 1.22 upgrade process with AI worked almost flawlessly. The only real issue I hit was a small documentation gap in Microsoft’s official upgrade guide. I successfully tested this prompt-driven approach with Claude Sonnet 4 (via GitHub Copilot) across multiple projects and SPFx solutions.
For me, this AI-assisted upgrade flow is absolutely worth using. Instead of spending hours on a manual SharePoint Framework upgrade, the entire SPFx with Heft migration can be completed in minutes.
Because the workflow builds in a safety net, I can decide at any point whether to keep or discard the upgrade branch without risking my main codebase.
What I appreciate most is that this method is reproducible and applies the same automated upgrade process to every SPFx project. Once everything is properly documented, upgrading to SPFx 1.22 with Heft becomes almost a no-brainer.
Top comments (0)