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.
Summary
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.
Corey Roth's Blog 