"npm outdated" showing my @microsoft/sp- packages being badly outdated.

How to update your SPFx webpart to a new version of SharePoint Framework

This post was most recently updated on July 26th, 2019.

Reading Time: 6 minutes.

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.

Just recycling my unused node modules...
Just recycling my unused 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.

"npm outdated" showing my @microsoft/sp- packages being badly outdated.
“npm outdated” showing my @microsoft/sp- packages being badly outdated.

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/sp-core-library@latest --save
npm install @microsoft/sp-module-interfaces@latest --save
npm install @microsoft/sp-webpart-base@latest --save
npm install @microsoft/sp-webpart-workbench@latest --save
gulp --update

Or with said explicit version number:

npm install @microsoft/sp-core-library@1.8.2 --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

Run this:

npm install

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.

In my packages.json -file, I had different versions of some packages for "dependencies" and "devDependencies". This causes errors during npm install and will cause confusion down the line.
In my packages.json -file, I had different versions of some packages for “dependencies” and “devDependencies”. This causes errors during npm install and will cause confusion down the line.

Good stuff.

Step 5: Boot your stuff and get coding

Now you’re ready to close down your Visual Studio Code and reopen it again.

Et voíla!

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:

Additional tooling

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:

References

Some sources for this blog article and other further reading below:

Antti K. Koskela

Antti Koskela is a proud digital native nomadic millennial full stack developer (is that enough funny buzzwords? That's definitely enough funny buzzwords!), who works as a Solutions Architect for Valo Intranet, the product that will make you fall in love with your intranet. Working with the global partner network, he's responsible for the success of Valo deployments happening all around the world.

He's been a developer from 2004 (starting with PHP and Java), and he's been bending and twisting SharePoint into different shapes since MOSS. Nowadays he's not only working on SharePoint, but also on .NET projects, Azure, Office 365 and a lot of other stuff.

This is his personal professional (e.g. professional, but definitely personal) blog.
mm