Upgrading SPFx to the Latest Version SPFx 1.20.0 - lessons learned
Introduction
With the release of SPFx 1.20.0 in September 2024, I decided to upgrade an existing SPFx solution to the latest version following a post by Microsoft 365 & Power Platform Community on Linkedin This process can be challenging, especially when dealing with dependency version conflicts. In this blog post, I’ll walk you through the steps to upgrade your SPFx solution to version 1.20.0, including installing Node.js 18.18.0, using the CLI for Microsoft 365 to generate upgrade instructions, and addressing common issues.
Please bear in mind that the steps differ per SPFx version and solution. Remember I failed to upgrade the solution I wanted due to my lack of knowledge of Gulp and webpack. The solution in question is rss reader.
Installing Node.js
First, ensure you have Node Version Manager (NVM) installed on your machine. Then, install Node.js version 18.18.0.
nvm install 18.18.0
Installing SPFx Toolchain
Next, install the SPFx toolchain globally using npm.
npm install gulp-cli yo @microsoft/generator-sharepoint --global
Checking SPFx Version
Verify the installed versions of Node.js and SPFx to ensure they are correct.
npm ls --depth 0 -g
Using CLI for Microsoft 365 to Upgrade SPFx
Install the CLI for Microsoft 365:
npm install -g @pnp/cli-microsoft365
Run the following command to generate upgrade instructions:
m365 spfx project upgrade -v 1.20.0
Generated Instructions
The CLI for Microsoft 365 will generate a set of instructions to upgrade your SPFx project. Here is an example of the generated instructions:
[
{
"description": "Upgrade SharePoint Framework dependency package @microsoft/sp-core-library",
"id": "FN001001",
"file": "./package.json",
"position": {
"line": 19,
"character": 5
},
"resolution": "npm i -SE @microsoft/sp-core-library@1.20.0",
"resolutionType": "cmd",
"severity": "Required",
"title": "@microsoft/sp-core-library"
},
{
"description": "Upgrade SharePoint Framework dependency package @microsoft/sp-lodash-subset",
"id": "FN001002",
"file": "./package.json",
"position": {
"line": 20,
"character": 5
},
................................................................
{
"description": "Update @microsoft/teams-js SDK version in .yo-rc.json",
"id": "FN010010",
"file": "./.yo-rc.json",
"position": {
"line": 13,
"character": 7
},
"resolution": "{\\\n \"@microsoft/generator-sharepoint\": {\\\n \"sdkVersions\": {\\\n \"@microsoft/teams-js\": \"2.24.0\"\\\n }\\\n }\\\n}",
"resolutionType": "json",
"severity": "Recommended",
"title": ".yo-rc.json @microsoft/teams-js SDK version"
},
{
"description": "If, after upgrading npm packages, when building the project you have errors similar to: \"error TS2345: Argument of type 'SPHttpClientConfiguration' is not assignable to parameter of type 'SPHttpClientConfiguration'\", try running 'npm dedupe' to cleanup npm packages.",
"id": "FN017001",
"file": "./package.json",
"resolution": "npm dedupe",
"resolutionType": "cmd",
"severity": "Optional",
"title": "Run npm dedupe"
}
]
That translates to running these cmdlets. Bear in mind the output will differ depending on SPFx versions and projects.
Upgrading Packages
Run the following commands to upgrade the packages as per the generated instructions:
npm i -SE @microsoft/sp-core-library@1.20.0
npm i -SE @microsoft/sp-lodash-subset@1.20.0
npm i -SE @microsoft/sp-office-ui-fabric-core@1.20.0
npm i -SE @microsoft/sp-webpart-base@1.20.0
npm i -SE @microsoft/sp-property-pane@1.20.0
npm i -SE @microsoft/sp-adaptive-card-extension-base@1.20.0
npm i -DE @microsoft/sp-build-web@1.20.2
npm i -DE @microsoft/sp-module-interfaces@1.20.2
npm i -DE @rushstack/eslint-config@4.0.1
npm i -DE @microsoft/eslint-plugin-spfx@1.20.2
npm i -DE eslint@8.57.0
npm i -DE @microsoft/eslint-config-spfx@1.20.2
After upgrading the packages, the package.json file might look like
{
"name": "react-rssreader",
"version": "1.1.0",
"private": true,
"engines": {
"node": ">=16.13.0 <17.0.0 || >=18.17.1 <19.0.0"
},
"resolutions": {
"@types/react": "16.8.8"
},
"main": "lib/index.js",
"scripts": {
"build": "gulp bundle",
"clean": "gulp clean",
"test": "gulp test"
},
"dependencies": {
"@fluentui/react": "8.106.4",
"@microsoft/sp-adaptive-card-extension-base": "1.20.0",
"@microsoft/sp-core-library": "1.20.0",
"@microsoft/sp-lodash-subset": "1.20.0",
"@microsoft/sp-office-ui-fabric-core": "1.20.0",
"@microsoft/sp-property-pane": "1.20.0",
"@microsoft/sp-webpart-base": "1.20.0",
"@pnp/logging": "3.22.0",
"@pnp/spfx-controls-react": "3.19.0",
"@pnp/spfx-property-controls": "3.18.0",
"@types/handlebars": "4.0.39",
"ace-builds": "1.32.5",
"common-tags": "1.8.0",
"handlebars": "4.7.7",
"handlebars-helpers": "0.8.4",
"moment": "2.29.0",
"react": "17.0.1",
"react-ace": "10.1.0",
"react-dom": "17.0.1",
"react-moment": "1.1.3",
"ts-md5": "1.2.4",
"tslib": "2.3.1",
"xml2js": "0.4.19"
},
"devDependencies": {
"@microsoft/eslint-config-spfx": "1.20.2",
"@microsoft/eslint-plugin-spfx": "1.20.2",
"@microsoft/rush-stack-compiler-4.7": "0.1.0",
"@microsoft/sp-build-web": "1.20.2",
"@microsoft/sp-module-interfaces": "1.20.2",
"@rushstack/eslint-config": "4.0.1",
"@types/react": "17.0.45",
"@types/react-dom": "17.0.17",
"@types/webpack-env": "1.15.2",
"ajv": "6.12.5",
"eslint": "8.57.0",
"eslint-plugin-react-hooks": "4.3.0",
"gulp": "4.0.2",
"unlazy-loader": "0.1.3",
"webpack-bundle-analyzer": "3.9.0"
}
}
Updating .yo-rc.json
Update the .yo-rc.json file with the following changes:
- “version”: “1.20.0”,
- “nodeVersion”: “18.18.0”,
- “@microsoft/teams-js”: “2.24.0”,
Common Issues and Fixes
Node Version Conflicts
Upgrading the packages help but order of upgrade matters
Order of Package Installation
The order of package installation matters. For example, install eslint before @rushstack/eslint-config to avoid errors.
If trying to install npm i -DE @rushstack/eslint-config@4.0.1 before npm i -DE eslint@8.57.0 it will end up with errors.
Fixing ESLint Warnings
If you encounter ESLint warnings, such as:
Warning - lint - src\controls\PropertyPaneTextDialog\IPropertyPaneTextDialogInternalProps.ts(1,1): error @typescript-eslint/ban-types: Definition for rule '@typescript-eslint/ban-types' was not found.
The ESlint rules don’t exist by default in SPFx 1.20.0 scaffolding project, hence I removed them from file .eslintrc.js
// STANDARDIZED BY: @typescript-eslint\eslint-plugin\dist\configs\recommended.json
//
// CONFIGURATION: By default, these are banned: String, Boolean, Number, Object, Symbol
'@typescript-eslint/ban-types': [
1,
{
'extendDefaults': false,
'types': {
'String': {
'message': 'Use \'string\' instead',
'fixWith': 'string'
},
'Boolean': {
'message': 'Use \'boolean\' instead',
'fixWith': 'boolean'
},
'Number': {
'message': 'Use \'number\' instead',
'fixWith': 'number'
},
'Object': {
'message': 'Use \'object\' instead, or else define a proper TypeScript type:'
},
'Symbol': {
'message': 'Use \'symbol\' instead',
'fixWith': 'symbol'
},
'Function': {
'message': 'The \'Function\' type accepts any function-like value.\nIt provides no type safety when calling the function, which can be a common source of bugs.\nIt also accepts things like class declarations, which will throw at runtime as they will not be called with \'new\'.\nIf you are expecting the function to accept certain arguments, you should explicitly define the function shape.'
}
}
}
],
HTTP Base Errors
If you encounter errors related to SPHttpClientConfiguration
Try runnning
# Check for duplicate packages
npm ls @microsoft/sp-http-base
# Deduplicate packages
npm dedupe
If the issue persists, use the following PowerShell script to clean up and reinstall packages:
# Remove node_modules folder
Remove-Item -Recurse -Force .\node_modules
# Remove package-lock.json file
Remove-Item -Force .\package-lock.json
# Clean install
npm install
Node Engine
SPFx 1.18.2 works on node 18.17.1. If ever you have installed latest Node v18.18.0 or later, ensure to update the engines node parameter property from 18.17.1 to >=18.17.1 <19.0.0 within file .\package.json and .yo-rc.json.
Check the file package-lock.json. In case it is referencing old SPFx versions and node version, delete the file and run npm i
WebPart Not Loading
Run the following to test your webpart.
gulp clean
gulp build
gulp serve
If successful, your webpart will load in the workbench. In my case the web part refuses to load in the toolbox despite ensuring gulp serve is running and refreshing the page. It may happen like in my case unable to get the webpart loads in local workbench and unable to package as a solution due to missing file temp\manifest.js despite a clean build from the terminal.
That’s the message from the local workbench.
Your web part will not appear in the toolbox. Please make sure “gulp serve” is running in a web part project. Please refresh the page once “gulp serve” is running.
I have tried it on both node v18.18.0 and v18.20.4 upgrading the SPFx project with no luck.
SPFx CLI Doctor
Use the SPFx CLI Doctor to identify and fix issues:
m365 spfx doctor
Build solution from scratch
In case above steps don’t work, scaffold a new project using latest SFPx 1.20.0. Check the webpart/solution renders first through gulp serve to ensure there is no environment setup issues. Then copy the src file, gulpfile.js, config/config.json, tsconfig.json from exisiting old solution built using older packages. Add missing packages into package.json for the solution.
npm i
gulp clean
gulp build
gulp serve
Again I failed to upgrade the solution.
Fix Incompatibility of Packages
Fortunately, help was at hand from Nello D’Andrea who kindly assisted after several failed attempts by myself and others. We identified issues with the incompatibility of webpack, gulp, and npm packages but were unsure how to resolve them. Nello made the following crucial changes:
- Removed the handlebar-helpers package, which had not been updated for 7 years, and replaced most of the helpers with lodash or native JavaScript functions.
- Refactored the Gulp configuration for compatibility with Webpack 5 and updated npm packages.
- Fixed a bug with custom templates that caused the web part tab to freeze (render loop), likely due to the custom templates not being extensively used in the past.
Conclusion
Upgrading your SPFx solution to the latest version can be challenging, but following these steps and addressing common issues can help ensure a smooth upgrade process. The upgrade process may involve replacing old, incompatible packages and refactoring the solution to work with the new packages.. Regularly updating your SPFx projects ensures you benefit from the latest features and security improvements.