SPFx solutions don’t necessarily need to be upgraded. That doesn’t mean you shouldn’t upgrade them. In this blog post, I’ll explain the SPFx upgrade process, why it matters, and share some valuable tips and tricks from real-world experience.

Table of Contents

The SPFx upgrade process

Upgrading your SPFx solutions means that you will at least move to a newer version of the SPFx related packages and their dependencies. Microsoft has some Learn documentation about the upgrade process. You can find information here and here .

My recommendation is to adopt and use the excellent Microsoft 365 CLI or the SPFx Toolkit Extension , which under the hood uses the Microsoft 365 CLI.

Why Upgrade your SPFx components ?

It is like the maintenance for your car. You can drive as long as it drives and you may not need to go the garage, but the more you delay your service appointment, the higher the risks you may take.

  • Continual Evolution: The SPFx framework, launched in February 2017 at v1.0.0, has grown to v1.20.8 —eight years and around 20 releases. Each version brings new features, performance improvements, and security updates.
  • Security & Performance Fixes: Regular updates address known vulnerabilities and optimize your solution’s performance.
  • Easier Maintenance: Keeping your components current reduces technical debt and streamlines ongoing maintenance.
  • Better Compatibility: Regular upgrades ensure smooth integration with third-party libraries (e.g., PnP) and reduce version conflicts.

When should you upgrade ?

There is no better season or month, but rather than letting changes pile up, it’s far more efficient to schedule an annual upgrade (or similarly frequent interval). This way, you avoid facing a huge, time-consuming “mountain of work” and keep your SPFx solutions secure, compatible, and high-performing.

The SPFx Upgrade Tooling

There is no automatic upgrade tool, but you will get a very detailed report on how to upgrade your SPFx solution.

The Microsoft 365 CLI is the first tool you can use to generate the upgrade report. Here an example on how to generate a report for the SPFx version 1.20.

m365 spfx project upgrade --toVersion 1.20.0 --output md > "upgrade_1_20_0-report.md"

The second tool is much easier and just need two clicks, after you have installed it in Visual Studio Code. With the help of the SPFx Toolkit Extension, just click on “Actions → Upgrade Project SPFx Version,” and you then have your upgrade report generated.

Anatomy of the Upgrade Report

The generated upgrade report is typically split into two main sections:

  • Findings : step-by-step instructions Working one npm package at a time. It’s more thorough but is slower. If an error arises, it’s easy to see exactly where it happens.

  • Summary : a condensed list of the same upgrades. A single big set of instructions, which can be faster. But if something fails halfway, you need to compare your new package.json with the pre-upgrade version to see where it went wrong.

Note: The file changes—like modifications to your .ts or config files—are the same in both approaches.

Both can fail if there’s a conflicting package version somewhere. If that happens, consider a manual approach.

When Package Upgrades Fail

When your automatic approach (i.e., the CLI script or a summary approach) fails to upgrade certain packages because of version conflicts or unresolvable peer dependencies, you can:

  • Switch to “Manual Mode”: => Manually update each relevant entry in package.json as dictated by the upgrade instructions. => Don’t run npm install until you’ve updated all packages, removed old ones, and added new ones. => Then do a fresh npm install to finalize the process.

Real-Life Scenarios: Tips & Tricks

  • SPFx Upgrades & Non-SPFx Packages The CLI instructions focus on SPFx-related items only. If your solution uses packages like PnPjs, you’ll have to plan those upgrades separately.
  • Test the Upgrade Process Before upgrading your entire enterprise portfolio, try it on a few solutions. Document your experiences meticulously.
  • Document the Upgrade Path
  • Keep a record of your Node, NPM, and SPFx versions. Commit your generated “upgrade report” so your team can see exactly what was done. Maintain a Working Copy
  • Always keep a copy of the original solution in case you need to roll back or compare.

Conclusion

Performing regular maintenance on your SPFx solutions ensure that your solutions works securely and smoothly, like you expect it from your car.