Search This Blog

Versioning SharePoint Framework Packages

TL;DR: Package versioning in SPFx web parts is confusing. Your sites will notify you that an upgrade is available, but will automatically use the latest version of your code regardless.
Package versioning behaviour in the SharePoint Framework is currently a little idiosyncratic, and it recently caused us a few headaches. It seems that from a versioning perspective SharePoint (incorrectly) expects the SPFx packages to behave like SharePoint Add-ins. In this post I'll run through some of the issues we encountered and how we worked through it.

Context

You can version an SPFx package in three places:

The SharePoint package manifest, in the package-solution.json file.

The component manifests, in one or more .manifest.json files.

The NPM package manifest, in the package.json file.

In this post we're looking at the SharePoint package manifest (package-solution.json) as this is the version number that SharePoint reads and propagates when you deploy a package to the App Catalog.

The Problem

Recently I created a neat little "Project Summary" web part for a client using the SharePoint Framework. I packaged it up and deployed it to the client's App Catalog site, and the client added it to the landing page on around 150 team sites.

Then the client reported a bug. No problem - we duly fixed the issue, bumped the version number in the package-solution.json manifest file, and deployed the updated package to the App Catalog. We then started to see update prompts on the team sites that includes the web part, like this:

And when you click through:

In other words, I was seeing the versioning mechanism for the old SharePoint add-ins model. At this point I started to get a headache - I didn't want to tell my client to update the web part manually on 150 sites, and I couldn't find any hooks for automating the update. I posted a question about bulk updates on Stack Exchange. The most helpful responses advised me to leave the version number unchanged when pushing out updates (not ideal from the good software development practices, but I'm ever the pragmatist).

Pushing out an updated .sppkg package with an unchanged version number got rid of the update prompts on sites that already included the web part solution. However, this approach introduced a whole new problem on sites that didn't already include the solution. On attempting to add the solution from the Site Contents page, users were presented with the error:

Sorry, something went wrongA different version of this App is already installed with the same version number. You need to delete the app from the site and the site recycle bin to install this version.
None of this was particularly helpful - the web part was not installed on the site and did not feature in any recycle bins.

What's Going On

It didn't occur to me (despite some of the responses to my question alluding to it) that any existing instances of the web part within the tenancy would automatically use the updated code, despite prompting the owner to "get" the latest update. (You can kind of figure it out if you look at what you're deploying to your CDN - although your JavaScript bundle gets a different unique name every time, the file name for the JSON manifest doesn't change - in other words, you're replacing the manifest every time, and the manifest always points to the latest bundle.)

Here's a quick proof-of-concept - I created the world's dumbest web part. All it does is display a version number as static text. I deployed it to the App Catalog on a dev tenancy, then added it to a site:

Next, I bumped the version number in package-solution.json, updated my static text, and deployed the new package to the App Catalog. I browsed back to my site, refreshed the page, and immediately saw the new version:

However, the Site Contents page tells us we're still running version 1:

And gives us the opportunity to "get" the latest update:

Pretty confusing, right? If you click GET IT, SharePoint will go through the motions and the Site Contents page will display the updated version number. But it won't make any difference to your SPFx web parts - these will already be using the updated version of your code.

Conclusion

At the moment, the versioning story for SPFx components is messy. For now, we figured the best way through this is:

You do need to bump the version numbers when you deploy an updated package, otherwise you risk running into the A different version of this App is already installed with the same version number error.

Any instances of the web part in your tenancy will automatically use the updated version.

You can ignore the update prompts on the Site Contents page. (If site owners do choose to "get" the latest version, the only thing that will change is the version number displayed on the Site Contents details view.)

Comments

Post a Comment

Popular posts from this blog

If you use SharePoint Designer 2013 to build workflows, there's a fair chance you'll have come across the following error message:Server-side activities have been updated. You need to restart SharePoint Designer to use the updated version of activities.
Needless to say, restarting SharePoint Designer rarely makes the error go away. The usual advice is:

Approach 1: Clear the cache folders
See for example How to Clear Your SharePoint Designer 2010/2013 Cache. If you've just deployed some custom workflow activities to your site, this will probably solve your problem (and you should clear the cache folders every time you deploy custom activities). If the error occurs spontaneously, this approach often won't help.

Approach 2: Reinstall SharePoint Designer
This might work if you've got a preview version of SharePoint Designer installed. If not, it's unlikely to help. It didn't work for me, and it didn't work for countless others on the forums.

Today's problem occured after I restarted a Hyper-V based SharePoint 2013 farm (Windows Server 2012, one SharePoint 2013 machine, one SQL Server 2012 machine, one DC). I fired up Central Administration and was hit with the following error:

After checking the obvious things - testing connectivity to the DB server, checking the SQL service was running, verifying permissions, etc - I initially figured this was an issue with my Hyper-V snapshots being out of sync, so I ran the SharePoint Products Configuration Wizard. This hit me with the following error:

Failed to detect if this server is joined to a server farm. Possible reasons for this failure could be that you no longer have appropriate permissions to the server farm, the database server hosting the server farm is unresponsive, the configuration database is inaccessib…