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.


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 wrong
A 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.


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.)
Right, glad we've cleared that up... I'm off for a lie down.


  1. This is really useful and reflects exactly what we are seeing. One question though - how are you deploying new app to catalogue? If we simply upload and replace then our web part no longer appears in the gallery so cannot add to new pages. If we delete old app and upload new file it works.

    New to SPFx so please excuse if simplistic question.

    1. Hi Steve - sorry about the delayed response. I think it depends on whether you're including the client-side assets in the package you deploy to the App Catalog. When I wrote this, we didn't have the option to bundle script files into the sppkg - I deployed the JavaScript files etc to a CDN, and I deployed the package to the App Catalog on Office 365. We also didn't have the option to deploy globally without having to add the app to individual sites. Since SPFx 1.4 was released, the package you generate will include the script files by default (unless you change the value of the includeClientSideAssets flag in your package-solution.json file). If everything is in your package, then I think you will need to increment version numbers and you will need to explicitly "update" your app on individual sites.

      I'll update this post once I've figured out exactly how versioning works for SPFx >1.4.

    2. Does this article still holds true for SPFx >1.4 version ?

  2. FYI, you can put a powershell script in the root of your SPFx project and run the following:

    Write-Host "Auto-incrementing SPFx Solution Version..." -foregroundcolor "green"
    $tokens = $null
    $config = Get-Content '.\config\package-solution.json' -raw | ConvertFrom-Json
    $solution_version = $config."solution".version
    $feature_version = $config."solution".features.version
    $tokens = $solution_version.Split(".")
    Write-Host $tokens
    $major = [int]( $tokens[0])
    $minor = [int]( $tokens[1])
    $patch = [int]( $tokens[2])
    $fix = [int]( $tokens[3])
    $new_fix = $fix + 1 # updates patch... must update below
    $Version = ([string] $major)+"."+ ([string] $minor ) +"." + ([string]$patch)+"." + ([string]$new_fix)
    $config.update | % {
    $config."solution".version = $version
    if ($solution_version -eq $feature_version) {
    $config."solution".features[0].version = $version
    Write-Host "Updated to" $Version

    $config | ConvertTo-Json -Depth 20 | set-content '.\config\package-solution.json'

  3. Excellent this works perfectly for my issue also.


Post a Comment

Popular posts from this blog

The target principal name is incorrect. Cannot generate SSPI context.

Server-side activities have been updated