7 Tips for upgrading to SPFx 1.13.0 (or any other version)

I’ve been testing Beta 13 of SPFx and wanted to share these tips.

Welcome SPFx beta versions

Upgrades to SPFx are usually painless, but sometimes (like in version 1.12.0), there are issues. The SPFx team now releases beta versions of each SPFx release giving us an opportunity to try our code with it before upgrading. As of writing, we are now on Beta 13. You may be wondering why it started with Beta 13. That simply means there were beta versions that they developed internally before making any of the versions public. As we see future beta versions of this release, don’t be surprised if it skips a few numbers as well.

Consider using nvm to use a different node version for beta

The yeoman generator install globally in node. This means if you need to switch between release and beta versions, it will be an issue. Pick a random version of node 14 to install with nvm and use that for your beta install. This will keep your release version in tact.

Create a new branch / clone to a new folder

While source control tools like git manage the code, our node_modules folder is not in source control. That means if you branch for your new beta and upgrade your node_modules, they will be the wrong version if you switch back to your release branch. If you need to switch around between release and beta versions this will quickly become time consuming. Create a new local folder and clone your repo into it. Now create a new branch. This lets you have separate node_modules folder allowing you to easily switch between release and beta versions.

Upgrade the dependencies in package.json

You can use the CLI for Microsoft 365, to help you with the upgrade commands for your package. However, you might be upgrading faster than the team has had a chance to update the tool. You may need to use a beta version of the CLI to get the latest updates for the beta version too. This usually works, but in the last version I used (v3.12.0-beta.e4850a1), it left out the devDependencies section. That was easily enough resolved though.

If you don’t want to use CLI, the other option is to use the generator to create a new SPFx project using the new version. You can then compare your package.json files to figure out what to update.

For external dependencies, watch out for use of the “^” sign in versions. When you run npm install, any dependency that published an update will get updated. While this may not be an issue, it might if there are breaking changes. I’ve had more than one case, where I am spending time troubleshooting changes in unrelated dependencies during an SPFx upgrade. Get rid of those carrots (^) before you run npm install.

Remove node_modules and package-lock.json

If you created a new clone of your repo, you won’t have to worry about using node_modules because you don’t have one yet. However, if you are upgrading in place, you should delete your node_modules folder now. If you don’t you will more than likely run into TS2345 errors in regards to HttpClientConfiguration. Don’t forget to remove package-lock.json as well, as Walkdek reminded me today.

Remove the local workbench

The local workbench is now gone. Specific to SPFx 1.13.0, make sure you remove the following line from devDependencies of your package-json file, otherwise npm install will fail.

"@microsoft/sp-webpart-workbench": "1.12.1",

You will also need to remove the reference to this in your serve.json file. Update the initialPage parameter to an online URL and remove the api section.

Introducing .npmignore

SPFx 1.13.0 introduces a .npmignore file to the project. While not a new concept, it new to the scaffolded code from yeoman for SPFx. This file simply tells npm which files not to include when your build a package. It contains files such as gulpfile.js, config, release, src, and temp. Use the CLI for Microsoft 365 or create a new project to see what you need to put in it.


While this post describes the process with SPFx 1.13.0, many of these tips will be useful when you perform future upgrades as well.

Published by coreyroth

Corey Roth is the Vice President of Engineering at UnlimitedViz where he helps build the tyGraph product line for data analytics in Microsoft 365. Corey is an eleven-time recipient of the Microsoft MVP award in Office Apps and Services. Corey helps ISVs develop mobile-first applications for Office 365 using technologies such as Ionic Framework and Azure. Corey has always focused on rapid adoption of new Microsoft technologies including Office 365 and Azure. In his spare time, Corey works with his wife, Jennifer, on their product BrewZap, a mobile app platform for breweries.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: