How to update SharePoint Framework for an SPFx webpart?

Time needed: 30 minutes.

Updating the SharePoint Framework

1. 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.

2. 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…}
   
   

   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” shows my @microsoft/sp- packages being badly outdated.}
   
   That’s a couple of packages out of date. A few major versions are 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 with @[versionnumber] to install a particular version.
   
   _{<pre lang=”powershell”>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
   </pre>}
   
   Or with said explicit version number:
   
   _{<pre lang=”powershell”>npm install @microsoft/[email protected] –save
   </pre>}
   
   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.
   
   
3. Update other dependencies

   The next thing to do is to update all other dependencies to the minimum required version (since that’s the version most likely to work). To do this, run the following:
   
   <pre lang="bash">npm update --save
</pre>
   
   

   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 the npm install and waiting for an hour (or so).

   Which, coincidentally, is going to be our next step.

4. Get all packages to your solution and resolve conflicts

   Run this:
   
   _{<pre lang="powershell">npm install
   </pre>}
   
   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 the 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:
   
   <pre lang="powershell">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' </pre>
   
   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 your project is complicated and there seems to be no end to conflicts and build failures, see this note.

5. Verify that your devDependencies are up-to-date

   If after installing any of 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.
   
   
   
   In 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 the npm install and will cause confusion down the line.}
   
   Good stuff.
6. 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 the next step

7. 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 the below:
   
   _{<pre lang=”powershell”>o365 spfx project upgrade –output md > report.md</pre>}
   
   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:
   
   https://tahoeninjas.blog/2018/06/12/upgrade-your-spfx-solution-to-sharepoint-framework-package-v1-5/
   
   https://blog.mastykarz.nl/upgrade-sharepoint-framework-project-office-365-cli/