Upgrading SharePoint Framework (SPFx) Projects with the Office 365 CLI

The Office 365 CLI is a great set of capabilities you can use to interact with Office 365 – which is platform independent. Because it’s written to run under Node.js®, it can run on any operating system. Since PowerShell requires Windows, it’s a handy-dandy toolkit for people on a Mac, for example.*

Using the Office 365 CLI, you can manage your Microsoft Office 365 tenant and SharePoint Framework projects on any platform. No matter if you are on Windows, macOS or Linux, using Bash, Cmder or PowerShell, using the Office 365 CLI you can configure Office 365, manage SharePoint Framework projects and build automation scripts.

While the capabilities in the Office 365 CLI are extensive, my favorite capability is spfx project upgrade. Its purpose is simple: to help you upgrade a SharePoint Framework (SPFx) project to the specified version.

The usage is simple, but the work it does for you is not. Basically, it analyses the files in your SPFx project and tells you what you need to do to upgrade to the version you specify.

Today, I wanted to upgrade a project from version 1.7.0 to 1.8.2. I simply typed this in the terminal window…

spfx project upgrade --toVersion 1.8.2 --output md > upgrade-report.md

…and after a few seconds, I had everything I needed to do in the upgrade-report.md file.

I tend to jump down to the Summary section, run whatever is in the Execute script section, which will look something like this:

npm i -SE @microsoft/[email protected] @microsoft/[email protected] @microsoft/[email protected] @microsoft/[email protected] @types/[email protected] @types/[email protected] [email protected] npm i -DE @microsoft/[email protected] @microsoft/[email protected] @microsoft/[email protected] @microsoft/[email protected] @microsoft/[email protected] 

…and then make whatever file edits are required. If you start at the top of the output file, you’ll have a lot more work ahead of you, though if you are interested in all the details it’s a worthwhile learning exercise the first few times.

I’ve found that whenever I upgrade an SPFx project from one version to another, it’s a good idea to delete node_modules and package_lock.json, restart my editor (VS Code these days), and run npm install afresh. You may not always have to do these steps, but if you do, you’re far less likely to have any issues after the upgrade. Far better than having to run npm install more than once, as it takes a while.

Thanks to all the great people who work on this PnP project, including waldekmastykarz, VelinGeorgiev, and many more.

Sharing is caring…

* I just noticed today that there is a cross-platform version of PowerShell. It looks like it runs on Windows, Linux, macOS and ARM so far.