How to Upgrade your SPFx Solutions to the Latest Version

Upgrading an existing SPFx (SharePoint Framework) solution to a new or updated version of SPFx is a crucial step to ensure the performance and security of your web parts or extensions. In an ever-evolving technical landscape, it is essential to keep up with the latest versions and best practices – not only to reflect the newest capabilities. However, an upgrade can be complex and requires careful planning and execution.

The SPFx framework offers developers the ability to create modern and innovative solutions in SharePoint Online with the goal to extend the basic functionality of SharePoint Online and to provide a standardized extensibility model. With each new version, improvements and new capabilities are introduced that either provide updates of the core modules (such as authentication, UI framework, M365 service integration and other) and make the development of solutions within the SharePoint Online or Microsoft 365 ecosystem easier. Upgrading to the latest version of SPFx ensures that your solution benefits from these enhancements while maintaining compatibility with other modern tools and libraries on which M365 and SharePoint development rely on.

Therefore, keeping the code base of your SPFX solutions actual is crucial. Before starting any upgrade, it is important to have the right tools and resources at hand. For me, these include the M365 CLI and the SPFx compatibility matrix (you’ll find all links below), which provides an overview of compatible versions of common tools and libraries. A structured upgrade approach is essential to ensure that all steps are executed correctly and in the right order.

Necessary Tools to use (resources)

Besides the standard considered toolchain for any SPFx solution, I made good experience with these handy „helpers“:

1. M365 CLI (https://pnp.github.io/cli-microsoft365/cmd/spfx/project/project-upgrade): Generates an upgrade report for your SPFx project to the specified version – and offers many other necessary features by the way… 😃
2. SPFx compatibility matrix (https://aka.ms/spfx-matrix): a reliable reference of compatible versions of common tools and libraries

The upgrade process: steps to consider

1. Make a new branch in your local git repo (I always call it „upgrade-spfx-v{spfxVersionNumber}“)

2. Create upgrade report by using M365 cli: m365 spfx project upgrade --toVersion 1.20.0 --output md > "upgrade report v{spfxVersionNumber}.md“ and commit it

3. Follow the the list of steps that are listed and under „findings“ in your upgrade report by maintaining this order (not the one from the listing) – and commit every (sub-) step to your local repo:

   1. Node modules dependencies in package.json
      1. upgrade all production and dev dependencies for all @microsoft/* modules
         ⚠️ It’s recommended to upgrade all related SPFx packages to the same version to maintain compatibility!
      2. Upgrade dev dependencies related to eslint
      3. Upgrade dev dependencies for rushstack/eslint-config and @microsoft/rush-stack-compiler-…
      4. Upgrade dev dependencies for typescript version (typescript)
      5. Upgrade production dependencies related to React (in case you do a React project)
      6. Upgrade (or change) production dependencies related to Fluent UI
      7. Upgrade node engine (property engines.node)
   2. yo generator dependencies in yo-rc.json
   3. Rush stack compiler dependencies in tsconfig.json

4. Delete node_modules folder and run a clean npm install to remove old modules and ensure you have only modules / dependencies from above

5. Build the dependency tree (hierarchical view of all installed packages) with npm ls to make sure your package dependencies are in a stable setup or if there’s still any missing or wrong packages
   👉 Example:

   my-extension@0.1.0 /Users/dummyUser/Coding/my-extension
   ├── @fluentui/react@8.106.4
   ├── @microsoft/decorators@1.20.0
   ├── @microsoft/eslint-config-spfx@1.20.2
   ├── @microsoft/eslint-plugin-spfx@1.20.2
   ├── @microsoft/generator-sharepoint@1.17.4 invalid: "1.20.0" from the root project # 👈 see this error!
   ├── @microsoft/rush-stack-compiler-4.7@0.1.0
   ├── @microsoft/sp-adaptive-card-extension-base@1.20.0
   ├── @microsoft/sp-build-web@1.20.2
   ├── @microsoft/sp-core-library@1.20.0
   ├── @microsoft/sp-dialog@1.20.0
   ├── @microsoft/sp-listview-extensibility@1.20.0
   ├── @microsoft/sp-module-interfaces@1.20.2
   ├── @pnp/graph@3.22.0
   ├── @pnp/sp@3.22.0
   ├── @pnp/spfx-controls-react@3.17.0
   ├── @rushstack/eslint-config@4.0.1
   ├── @types/react-dom@17.0.17
   ├── @types/react@17.0.45
   ├── @types/webpack-env@1.15.3
   ├── ajv@6.12.6
   ├── eslint@8.57.0
   ├── gulp@4.0.2
   ├── react-dom@17.0.1
   ├── react@17.0.1
   ├── tslib@2.3.1
   └── typescript@4.7.4
   
   npm error code ELSPROBLEMS
   npm error invalid: @microsoft/generator-sharepoint@1.17.4 /Users/dummyUser/Coding/my-extension/node_modules/@microsoft/generator-sharepoint
   npm error A complete log of this run can be found in: /Users/dummyUser/.npm/_logs/2025-01-09T23_02_57_872Z-debug-0.log
   

6. Clean up any missing or wrong dependencies from the node dependency tree (if there are any)

7. Upgrade the .nvmrc file to reflect the necessary node version for this project (check SPFx compatibility matrix for reference)

8. Delete the upgrade report

And then: clean up your code base and dependencies to other modules and libraries

After having upgraded your SPFx solution without any errors related to the used npm packages (modules) and the dependencies, you possibly have to refactor your code base (aka you implementation of the webpart, extension, …) in order to clean up invalid references to dependencies (modules):

• When using Fluent UI libraries, most likely you have to adjust your SASS import paths for CSS references (in your .SCSS styles) as well as UI components (in your React components). Cumbersome errors occur very often because of modules that have been replaced by @fluentui/react. In case you’re using @fluentui/react version 8.x, you have to up update import statements:
  1. SASS import: use correct path by using this directive: @import '~@fluentui/react/dist/sass/References‘;
  2. React components: change path to import UI components by using this import statement (example): import { Stack } from "@fluentui/react“
• If you use third-party libraries such as PnPjs or Reusable React controls, you have to take into account to upgrade the respective modules accordingly
  • If you’re getting ESLint warnings related to @typescript-eslint/ban-types, just remove their definitions from .eslintrc.js file