SPFX and Library Versioning

SFPX library versioning

Setting the stage

So, the SharePoint Framework has a bit of a tricky position to balance. On one hand, it is effectively a set of javascript libraries, and the normal way for people to develop javascript solutions is to pull specific versions of all their dependencies, build the solution, and when it runs only the solution you build is running. In other words, the solution "owns" the entire app. However for the vast majority of SPFX solutions (all of them at the moment), the solution is only a component of the overall page, and that overall page is "owned" by SharePoint itself. The simple way to solve that interdependency is to simply say "all components are iFrames". Luckily - we already have that solved - SharePoint Add-ins. However unless you need the security or isolation of an iFrame, it's not really the best solution from a user experience. Instead, you want to be hosted in the same page (and thus the same js application). So we are in a world at lot closer to the classic .net, on-prem SharePoint environment, where you compile against a known interface, but the actual library can change from update to update (and version to version).

Another twist

It could be possible for every component to bundle the specific version of the framework that it needs, but that could post a horrible performance penalty. If you happened to have 10 different components on the page, all built at different times, you could conceivably be downloading 10X the amount of code. Additionally, bug fixes and patches to the bundled components wouldn't be picked up, and there could be an untestable matrix of simultaneous versions interacting.

Solution

Instead, as stated above, we've taken an approach more aligned with the server world. We have a set of library packages (SPFX) that we continue to improve, with typical semver versioning. So for example, GA has 1.0.0 of @microsoft/sp-loader, and every week or two, that version will bump. The goal is to keep major version bumps to an absolute minimum, and instead make additive changes that are backwards compatible. Any change that breaks backwards compatibility is a bug, and the change would be reverted, or it would result in a new major version of the library.

Library manifests

A slight detour here. So as you may have picked up in your development on SPFX, there are two parts to each component (a component being a library, webpart, etc.). The manifest, and the actual javascript bundle that contains the component. The base SPFX components are the same, and they support a multi-version manifest file. So for any given component, it will say "Hey, this is sp-http, here is some information on it, version 1 is currently served by /CDN/build/spfxlibraryA.js and version 2 is current served by CDN/build/spfxlibraryA2.js". The infrastructure is in place for the multi-version assemblies, but at the moment all of the assemblies only have a single version.

The build phase

When you build your project using our build tools, the manifest generated contains some information that states what version of each library was used. In the loaderconfig section of the manifest, you will see something like this -

"@microsoft/sp-core-library": {
    "type": "component",
    "version": "1.0.0",
    "id": "7263c7d0-1d6a-45ec-8d85-d4d1d234171b"
  }”

Runtime

This is what the sp-loader component uses to determine which library to load. It asks the system “hey, give me the manifest for 7263c….. version 1.0.0 please”, and it gets back a manfest for component 7263c… version 1.1.7, which backwards compatible with version 1, and loads it if no one else has. This allows two important things to take place.

• Only one copy of each major version of a package is loaded onto the page. This keeps the payload smaller and the code simpler.
• Any updates to the framework are incorporated without needing a developer to rebuild and redeploy the solution. So as we fix bugs, increase performance, handle scenarios that we were unaware of in the past, the code picks them up immediately.

Can you do this?

Yes* – the concept of an SPFX library is build into the system, and 3rd party developers will be able to create them as well. *We are working on finalizing the work in the toolchain to allow you to produce them.

Moving forward

It is our goal to not create major versions if at all possible. To that end, we’ve made decisions up front that appear to be a bit awkward. For example, the SPHttpClient class. It would have been a simpler implementation to have a bunch of default settings that always apply, but then if we changed the default values (say ODataV5 became the ideal thing), everyone’s code would break, we would need to create a new version that really only differed in a minor way. Instead, we decided to make the defaults more explicit, we can add additional default configurations without breaking compatibility with existing code, etc.