ISO clarification on SPFx's dependent library versioning & rollout policy #325

andrewconnell opened this Issue Dec 22, 2016 · 29 comments


None yet

9 participants



  • Question
  • Typo
  • Bug
  • Enhancement / Suggestion
  • Additional article idea

After reviewing the docs in this repo, in the wiki & on as well as watching all the PnP stuff, I haven't been able to get the following answer... maybe I've missed something but asking around, seems to be an outstanding question...

What's the policy for rev'ing dependent library versions?
For simplicity, I'll focus on React since SharePoint has a strong bias towards React. If I am going to build web parts that use React & the Office UI Fabric, as a developer I need to understand how versioning is handled within SPFx / SharePoint as a whole.

This is important when you consider the following scenarios:

  • How do I know what version of React is on the page?
    • Supposed to be able to use React.version in the console, but it's not working on an empty workbench (local / O365 hosted)... React isn't defined...
  • My web part contains a workaround for something in React vX; React vX+1 addresses the bug but now my workaround will break in vX+1. I need to know what is being served up & when it will use vX+1
  • React introduces a new feature that I want to take advantage of in vX+1... my tenants are using vX... I need to plan for when vX+1 is rolled out in SPFx.
  • React introduces a breaking change in vX+1. My app is using the feature in vX. I need to plan for when vX+1 is rolled out in SPFx

If there is a policy... then...

  • where is it documented?
  • what's the process / timeline to see a new React version in a tenant?
  • how can a developer tell what version of React is on a page?
    • the bundles that are being returned in the O365 hosted workbench have comments stripped & appear to be coming from O365, not from the CDN's Facebook recommends... so it's hard to tell what version is being used
  • if MSFT plans to host them, will these new versions be rolled out with each generator update for local workbench testing & in first release tenants for

I'm not talking about updating my web part from vX to vX+1. I'm talking about something like React / Office UI Fabric. React has monthly drops & is progressing quickly.

andrewconnell commented Jan 5, 2017 edited

EDIT: raised this issue in the PnP JS SIG biweekly call on JAN-5-2017... the answer was that there is currently no policy but it's recognized as something that will be shared by GA.

IMHO: This is a pretty important thing... as many developers will not want to take a blind dependency on something, esp something so core to SPFx as React, with zero visibility into the versioning & upgrade story of that dependency.


I'd like to add to the question - other libraries such as Knockout or Angular, that also don't play nice when you have more than one version on the same page. Would be good to get guidelines on how to tackle this for all libraries and not specifically for react

sympmarc commented Jan 5, 2017

This is a set of issues all of us client side folks have been dealing with for years. It definitely gets harder when you are shipping a product with dependencies, for sure, but it is possible to have a good strategy.

One might think that turning to some outside parties who are already doing this well would be a great idea. This isn't an area where a "not invented here" mindset would be very useful.


I'm afraid it is not that simple, while in other fields usually there is a customer who knows what is running on his site, and can make everyone comply and play nice together, here we are talking pages that are dynamic-by-design, to the point that the end user is the one who can throw any number of different combinations of web parts and components to the page, in any order he like.
I do think this is quite a unique situation in web programming, which most libraries today do not handle very well (with exception of maybe jQuery noConflict option, which even that 99% of developers I know don't bother to use).

On the one hand, having MSFT say: Use vX for library Y might do the trick, but rouge developers might not comply, might load a different build by mistake or perhaps could not comply.
On the other hand, letting us load what we want and let us fight the version war ourselves is no solution at all... Some are more skilled than others, but it only takes 1 unskilled developer to bring down a whole page.

The only other option I can thing of is if MSFT will load the most common libraries for us, on a version they decide/control. But I am sure this will make a lot of people unhappy if they are forced into a choice.
IMHO - that should have been done a long time ago with jQuery on SharePoint... but that is another story.

andrewconnell commented Jan 5, 2017 edited

@sympmarc: This is a set of issues all of us client side folks have been dealing with for year

Totally agree... but that isn't the same issue, nor is it unique to client-side. The challenge SPFx introduces into this one is the fact you are deploying your customizations (that you control) into their environment (that you don't control) that has dependencies that you can't dictate / control... or at this time, have any visibility / expectation on the upgrade policy.

That's no different than us deploying our custom server-side components into SharePoint 2007 / 2010 / 2013 onprem before, except for one very significant difference: We're going from the dependencies having a 3yr ship cycle to a 1mo ship cycle. In the case of the issue I opened, React has monthly drops.


Yeah, the more frequent ship cycles is what makes it a bigger issue. But the main challenge in SharePoint is that even if you do a project for a customer and not a product, you still don't know what is going to be on the page alongside your code tomorrow.
That's usually not the case for web developers elsewhere so it isn't a common issue in web development and that's why (I assume) most libraries did not bother addressing this scenario.

Unless MSFT is going to rebuild angular, react, knockout etc. To be isolated- I don't see a simple solution for this issue except loading it as a part of the framework on a specific version for everyone to use.

Falkayn commented Jan 6, 2017

The question goes back to whether/how SPFx isolates different apps? If it can do it with some sort of magic - I had thought iframes where involved - then this may be a moot question. Otherwise, yes, it is a major issue.


The whole point was to not reply on iframes since they are too isolated and never render properly. They use isolation in the sense that your code is wrapped in self-calling functions so that solves name conflicts and the need for namespaces. The problem is that almost all libraries rely on global objects and that's the main problem. While some libraries can solve it like jQuery no conflict do. Others rely to heavily on globals and hook up many event listeners and lots of CSS classes it would just be nearly impossible to add isolation to them.


*rely, not reply...

Falkayn commented Jan 6, 2017

I thought the custom webpart's JavaScript libraries were going to be loaded in the ifame and the rendering was to be done in the SPFx 'canvas' area - but I haven't been keeping up with the work. Without some sort of 'magic' being involved we end up needing to rely on everyone being well behaved, and that includes the SharePoint devs themselves ;)


There are no iframes involved in loading libraries in SPFx, however if you use SPFx to load a library then it's loaded encapsulated. If you for example would have two web parts on the page one using jQuery 2 and the other jQuery 3 then it would all just work and both web parts would be using their correct version - even without using noConflict.

Falkayn commented Jan 6, 2017

Thanks Waldek! How does that relate to @andrewconnell original question then?


If I understand it correctly @andrewconnell's question is related not to libraries you load yourself and therefore control but to libraries provided to us by SPFx. Given that these libraries are not bundled together with the web part, but loaded from SPFx, it could be that with the next release of SPFx things don't work/work differently due to a change in one of the libraries.

Theoretically it should be possible to load React in web parts yourself rather than using the version provided with SPFx. So if you want more control about the libraries you're using, you could try doing that.


Waldek, your comment for jQuery is only partially correct since the global object will still only be registered once in one of the versions unless you use the no conflict in your code you may affect other components on the page in case they are relying on it and may break them (non SPFx ones as well as SPFx ones in case they even use a library that relies on window.jQuery object).

But yes, for the SPFx project, wrapping it inside a self calling function creates your own scope - I guess that is the "magic" Falkayn might be referring to. that's a good trick but far from issue-free, and the problem with CSS and JavaScript global objects and listeners will present a big challenge... i must say the current CSS solution they offer with dynamic class names doesn't make a lot of sense to me in real life where I would like to apply branding to my components separately than the component package.


You're right @shaipetel: if there are elements on the page that depend on the globally set library then there is a risk they will break. One could argue that depending on globally loaded libraries is something that you can safely do when you own the page and know its building blocks, which cannot be said of web part pages where users can change the composition at any time.


Well, sadly, lots of libraries do it even if it is not a good practice. Angular does it as well in some parts calling window.angular specifically looking for the global object.

Here is an excellent read about it which captures all aspects of how this magic works and the issues that come with it:

This is basically if I am not mistaken what you mean by "load your own library", which still might prove not to be a simple task without tinkering with the library's code.

My point is, the only way to really support this is if these libraries plan to support it. And currently AFAIK none of them support it by design, some might support it by chance with some wizardry.

An interesting topic indeed. Good night!


Let's keep this one on topic... this isn't a question about loading libraries... it's about dependencies. The fact MSFT includes React on the page & that you can't have two versions of React on the page makes the dependency question very valid & separate from dynamic module loading.


Not just react. I've seen OOB stuff in new experience that use knockout if I am not mistaken.

But I have to disagree on your take to limit just to talking about react since a solution/best practice/recommended approach should be adopted in my honest opinion to all major libraries.

chakkaradeep commented Jan 6, 2017 edited

Let me try to get more clarity on the problem here than trying to explore solutions:

  1. @andrewconnell 's concern is that there are set of libraries used by SharePoint. If my solution is using one such library, how do I manage those in my solution and how do I know what is available?

  2. There is also a greater issue of how do I as a developer manage the dependencies and its versions, especially some libraries that require global variables like jQuery, Angular 1.x etc.,\

I also want to stress that this is a problem even to internal Microsoft development teams as these use cases are common across client-side driven development unless you are building your own bespoke web application.

Regarding (1) - Agree there are very little information around, especially around React support. @patmill and @pgonzal will be the right folks to start this discussion. I am sure we have the info, its probably not documented or articulated in a good way.

Regarding (2) - Unless those dependencies are provided by Microsoft (something like what Wordpress does ), it relies a lot on the developers. This isn't different to challenges developers face today with client-side development. But IT IS DIFFERENT as to that now developers will have to think through on how their solution will be integrated natively into another solution. Pretty exciting and challenging at the same time. Add-ins necessarily don't have this problem as nothing really lives in SharePoint. You can consider an add-in almost a bespoke solution than an integrated native solution. You can also seek some help from browser cache as they usually do help if many web parts for example load the libraries from the same CDN path (a scenario common amongst enterprises than ISVs distributing web parts).

Some of it are easier if we are able to understand and use libraries that are suitable to scenarios. For example, while Angular 1.x is a great successful framework, it's just painful and entirely not of Angular 1.x's interest to build native widgets unless those widgets are inside one singular Angular app. It makes it harder to manage and deploy web parts in such cases. In other words, there is no one library/framework that will do everything and cater for all types of solution scenarios.

At Least for enterprises it can be recommended to validate/choose a set of libraries to depend and build their solutions on top of that.

I feel that answers to some of the points in (2) are a bigger problem that extends beyond SPFx and applies to generic client-side development. But we should see what we can do with (1).

Hope that helps. Thanks for starting this thread. Lets get more ideas and feedback!

andrewconnell commented Jan 6, 2017 edited

Thanks for chiming in @chakkaradeep ... totally agree to this:

I feel that answers to some of the points in # 2 are a bigger problem that extends beyond SPFx and applies to generic client-side development.

This issue had some comments get away from the main point which is # 1 above... my original concern.

I'm looking forward to hearing how you plan to handle this. Since posting this I've had a few reach out privately to me saying they are staying away from React because of the void of clarity on this topic... hopefully something before GA ;)

patmill commented Jan 6, 2017

@andrewconnell - can you confirm that the heart of your question is
"Microsoft is providing a version of React as an SPFX library.
What happens if I want to use an updated version of React that MSFT/SPFX hasn't wrapped?
What happens if SPFX starts including React 15.6 when you ask for react, and that has a breaking change (or a bug) that makes it break my webpart that was built using 15.4?
What happens if 3 different versions of react (or some other wrapped library or 1st party SPFX library) need to be loaded because there are 3 solutions on the page that require different versions?


@patmill yup... that pretty much nails it... except...

What happens if 3 different versions of react (or some other wrapped library or 1st party SPFX library) need to be loaded because there are 3 solutions on the page that require different versions?

This isn't possible to the best of my knowledge as React doesn't do well with multiple versions on the same page. I'm not 100% clear on this though as I haven't spent much production time with React other than learning samples to tinker a bit. This is just what came up when I went searching if this was an issue with React just as it is with Angular.

pgonzal commented Jan 6, 2017

If I understand right, this conversation is about third party packages being wrapped up as "client-side library" components, i.e. Microsoft has bundled them according to our guidelines, registered a manifest, and will take responsibility for releasing updates. The goal of course is to improve perf, by having everyone share a single bundle on the page.

Currently we do this for react and lodash because we need it ourselves. We have said that in the future, we will do this for a number of popular libraries, as a service for developers. Eventually we will probably also open up the "client-side library" component type so that third parties can do the same thing.

What happens if you release a web part that relies on React 0.14.x, and then we upgrade to React 0.15.x? We have two choices:

  1. Prove that it is forwards compatible, and then be on the hook for any accidental regressions.
  2. Create a major breaking version, which will then cause the library to be loaded side-by-side.

Either way, the goal is to ensure that an already shipped web part will not be broken, while allowing new web parts to use the new functionality.

wobba commented Jan 6, 2017

@patmill and this also goes into SPFx GA guidance. Should we as developers go React, as it's already loaded, or should we fear using it as it can be updated at will to match MS web part life cycles.

We need to know pro's and con's when advising customers, which is more important than what we actually use.


@wobba - We need to know pro's and con's when advising customers, which is more important than what we actually use.

Let's first start with a stated policy & then we can see what the pros & cons are from that. :)

pgonzal commented Jan 6, 2017

@patmill and this also goes into SPFx GA guidance. Should we as developers go React, as it's already
loaded, or should we fear using it as it can be updated at will to match MS web part life cycles.

I don't understand this fear. If you don't want to use Microsoft's bundle, you always have the option to maintain your own bundle of React.

wobba commented Jan 6, 2017

@pgonzal I'm no expert, but @andrewconnell said above that React doesn't play well with multiple versions on the same page, which I interpret as it might not be smart to load my version of it. I'll sit this one out until we have policy and all the answers :)


@pgonzal there's no fear here... just trying to get a clarification. Clearly, it's better to leverage a library that's already on the page instead of adding weight. And to do that, you need to understand what the maint. & support story is around what you're taking a dependency on.

The OP is 100% not about bundling your own stuff... it's simply to understand how MSFT plans to support & update stuff they are going to put on every page as well as what that policy is.

patmill commented Jan 6, 2017 edited

So a cursory test shows that react (at least the latest version of 15.4 and the SPFX version of 14.8) can be loaded onto the same page at the same time and not conflict. Now granted, this was not a deep dive into side-by-side, but nothing is currently barfing on me. My understanding is that you need to make sure to not have the two instances trying to modify the same react dom, but under normal circumstances that shouldn't happen (although we'll need to dive into custom controls in the property pane).
Also - please don't take this as a published statement stating exactly the state of the world and what GA will specify. We will give specific guidance in the next short while.

This is a super useful conversation.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment