This post was most recently updated on January 12th, 2020.6 min read.
Instead of being stuck on whatever version your SPFx project was originally created with, it’s possible and sometimes required to upgrade it afterwards to gain access to newer functionalities like integration with Microsoft Teams. This process, to me, is comparable to updating the .NET Framework version in your classic web application projects – while it’s sometimes a matter of simple configuration change and a rebuild, most of the time there’s a bunch of steps included and not all of them might be obvious or anywhere close to trivial to resolve. You might even have to dive deep into a dependency hell to figure out how to get all packages in compatible versions.
However, the tooling is there, and there’s plenty of community resources to help you get going – and I’m trying to explain the typical steps in this article, so that I don’t have to google them the next time I’m on a case like this again :)
Steps required to update your SPFx version in your webpart
Like always, I could be missing something. I’m just a guy documenting and sharing my solutions. If you find inconsistencies or have other comments, don’t hesitate to add them in the comments section below. Thanks!
On to the steps, then.
Step 0: Take a backup of your project
If you’re already using source control (and you should), you can pretty much skip this step. Just make sure all of your code is stored somewhere safe, so that you can revert easily if need be.
Step 1: Update your packages
First, you’ll need to update your different SharePoint Framework -related packages. After that, run gulp –update to make sure your config.json file is up-to-date with the latest antics of your packages.
You need to start the process by nuking your node_modules.
This step takes anything from half a second to about half an hour.
Next, fire up your console, and run npm outdated. Might be a good idea to open a new cmd instead of using the built-in one in VS Code. I’m sure that there’s an edge case somewhere that actually requires that approach.
From the output you can figure out which packages you’ll then need to update – anything that starts with @microsoft/sp- needs to be updated.
That’s a couple of packages out of date. A few major versions outdated, in fact.
Great – in this case, we’ll be updating to the latest, as 1.8.2 is exactly what we want (as of writing this in June 2019). Of course, in the snippet below, you can replace @latest by @[versionnumber] to install a particular version.
npm install @microsoft/[email protected] --save npm install @microsoft/[email protected] --save npm install @microsoft/[email protected] --save npm install @microsoft/[email protected] --save gulp --update
Or with said explicit version number:
npm install @microsoft/[email protected] --save
After this, you can verify that the update was a success by running npm outdated again. This time, the packages you just installed should’ve disappeared from the list.
Step 2: Update other dependencies
Next thing to do is to update all other dependencies to minimum required version (since that’s the version most likely to work). To do this, run the following:
npm update --save
This should update your packages to the required (wanted) version, albeit looking at the documentation it’s only supposed to update the packages to the latest minor version and shouldn’t update the major version at all. If you encounter issues with it, just run the npm install [package]@[version] for those packages as well… 🤷♂️
Don’t worry about some of the packages MISSING. They’ll be back after running npm install and waiting for an hour (or so).
Which, coincidentally, is going to be our next step.
Step 3: Get all packages to your solution and resolve conflicts
And go out for a walk, get some coffee from your local coffee shop selling organic near-sourced craft coffee, and don’t rush back. You’ve got time.
After running npm install, or later after building/bundling, you might run into errors. I mean, a lot of errors. A framework version update can cause a lot of grey hair – for more complex updates, you might want to take a look into additional tooling to figure out how to fix your stuff, but if your project is simple, you might survive with just a few adjustments.
I myself ran into this error:
Error - [tslint] Error: Cannot find module '@microsoft/rush-stack-compiler-3.2' Error - 'tslint' sub task errored after 18 ms Cannot find module '@microsoft/rush-stack-compiler-3.2'
Shown below in cmd:
This just means, that for whatever reason a required dependency – in this case, @microsoft/rush-stack-compiler-3.2 – has failed to install despite npm usually figuring these out. While there’s probably an actual root cause to this (and it would be lovely to fix that, right?), it’s the easiest to just install the packages to our project directly.
Make note of these packages, and then just nonchalantly proceed to run this for each of them:
npm install [packagename]@[requiredversion or latest]
You might need a certain version of the package. You can find out the required dependency from the documentation of the packages that might require it, for example on npmjs.com.
In my case, I discovered the right version I needed, and installed it – like so:
npm install @microsoft/[email protected]
(Note that the “-3.2” in the command above is not a version number. It’s part of the package name.)
To reiterate, if you project is complicated and there seems to be no end to conflicts and build failures, see this note.
Step 4: Verify that your devDependencies are up-to-date
If after installing any these packages you get a listing of dependencies that says “invalid”, like below, you need to verify your devDependencies are up-to-date with the other dependencies.
I my case, I had forgotten to update the devDependencies. That would’ve bitten me in the butt later as well, so it was lucky to get the error at this point already. I didn’t mind fixing it when it’s this obvious.
So, in short: if you have packages both as dependencies and devDependencies, make sure that the versions are the same.
Step 5: Boot your stuff and get coding
Now you’re ready to close down your Visual Studio Code and reopen it again.
At this point, you should be ready to start coding. Whatever fancy new features you’re hoping to use, should be available.
Wait, no, actually – I’ve got a ton of issues when building my code!
Welp, that’s a thing that happens sometimes. Check out:
To figure out which build errors you might get, and what to do to get around them, you can run Office 365 CLI’s “spfx project upgrade” command – it’ll give you an analysis of the steps you’ll need to take.
The command looks like below:
o365 spfx project upgrade --output md > report.md
Hugo Bernier and Walked Mastykarz already have great articles on how to use this tool, so I’m not going into details here. See their posts here:
Some sources for this blog article and other further reading below:
- How to run Robot tests on an Azure DevOps hosted agent? - March 4, 2021
- How to fix “Missing value for AzureWebJobsStorage in local.settings.json” when you’re debugging Azure Functions locally? - March 3, 2021
- How to copy-paste a table from Excel to WordPress without using plug-ins? - February 24, 2021