Fluentui: @uifabric/icons breaking change in 6.2.0

[bengry]

Not using the standard issue template since the template doesn't apply to this issue

Today (Nov. 20, 2018), @uifabric/icons v6.2.0 was published.
In this version, the file names of some of the icon packages changed (fd8af84b7deea5e883773f565477b74831cd6c81), e.g.:
fabric-icons-2-b9379dbc.woff -> fabric-icons-2-be6a5f70.woff
Since office-ui-fabric-react is dependent on it, using the following version range:

// office-ui-fabric-react/package.json
"@uifabric/icons": ">=6.1.1 <7.0.0",

When depending on office-ui-fabric-react alone (as expected), while using a custom CDN for hosting the icons, even without changing the office-ui-fabric-react version, the icons package got upgraded, breaking most icons.

Expected solution:

@uifabric/icons's version upgrade should've been a major one (to 7.0.0 probably). Alternatively, another way of fetching the icons, that's not file-name dependent should be implemented.

[KevinTCoughlin]

@Jahnp can you take a look?

[Jahnp]

@bengry, can you expand on your custom CDN usage here, preferably with a codepen or sample code, to help illustrate the issue? And, do the icons break if you do not use a custom CDN?

I suspect that if you are using office-ui-fabric-react with the stock initializeIcons call from @uifabric/icons the change would not be breaking. Custom CDNs or subsets can complicate that, and we may need to update docs to better call out how to use them safely.

I'm mobile and cannot diagnose at the moment but will take a closer look when I'm in.

[bengry]

@Jahnp We use our own CDN (or rather, the static server serving our app) due to security restrictions some of our customers have, which prevent them from making requests to the default CDN that @uifabric/icons (or is it office-ui-fabric-react) uses, which by the way - is not the SharePoint one, as mentioned in the docs, but one of Akamai. Maybe if it were a SharePoint it would be fine for us.

I can't create a codepen for this, since our service is not exposed, but the basic idea is that the files are statically hosted at: https://my-domain.com/assets/fonts/fabric-icons/<icon-file-name>.woff, and then in our code we have: initializeIcons('../assets/fonts/fabric-icons/'). This worked fine until v6.2.0 by the way.

At any rate, I assume it would work as well, like you mentioned - but nevertheless, it is a breaking change as far as @uifabric/icons is concerned, since it changed the file names. Subsequently, it's a breaking change for office-ui-fabric-react, for the same reason (just as much as a breaking change in any other dependency would be a breaking change - i.e. if you started using the unknown type from TS 3.0, then your .d.ts files would have them too, causing a breaking change for customers - requiring them to upgrade to TS 3.0).

[Jahnp]

Gotcha. Thanks for the details @bengry , and apologies for the disruption.

From quickly reviewing our docs, it seems we don't cover all the considerations & steps one should take when using a custom CDN. In this case, as you point out, the issue is likely that the call to initializeIcons from @uifabric/icons fails because the new font files generated by the Fabric icons tool are not on your CDN. In the short term, adding those font files to your CDN should fix the issue. They aren't available in the fonts folder because I neglected to add them in my latest PR--my bad, and I'll add them asap and update here with the PR when that's been done.

Longer term, if you definitely need to use your own CDN for the assets, you'd probably be much better served using the icons tool to maintain your own subset. This would give you fine control over the font file assets and the initialization code that fetches them, and would fully shield you from the changes we'll need to make to @uifabric/icons. It would also let you manage an exact of icons in your app to control bundle size.

Many teams within Microsoft use the tool to manage their own subsets, including OneDrive, SharePoint, Office.com, Outlook and more--I'd consider taking a look. Docs for that tool are here, and I'd be happy to answer any questions about it to help you onboard if you're interested.

For some brief background: the font file names and initialization code are programatically generated by the icons tool. It allows us to break up the very large (1700+) icon font into multiple subset "chunks" that can be fetched on demand when a request is made for an icon in a particular subset. Because the contents of those TS and font files are managed programatically, and will work unless there is an asset availability issue, I would not consider this a breaking change for @uifabric/icons itself. If you are not using a custom CDN, the package should work as expected.

That said, the considerations & expectations behind maintaining a custom CDN is not as clear as it should be. I'll take point on updating docs to make this clearer.

Also:

... the default CDN [...] is not the SharePoint one, as mentioned in the docs, but one of Akamai. Maybe if it were a SharePoint it would be fine for us.

To this point (emphasis mine): SharePoint Online uses Akamai's global CDN to back its production resources. The spoprod-a.akamaihd.net endpoint is one of several Akamai-based endpoints that's maintained by the SharePoint team. If it would keep things simpler for you to not manage a custom CDN, you can definitely rely on it.

[Jahnp]

@bengry - I've opened #7169 to add the missing font files. We'll publish a new version of @uifabric/icons asap. If you were relying on fonts being in that folder to update your CDN, this update was definitely a breaking change, and I apologize again for the disruption.

On that note, quick question: how are you pulling the font files for your custom CDN now? Do you have a build step that copies them from the fonts folder of @uifabric/icons?

[bengry]

@Jahnp Of course the Akamai CDN is not just a random one that got chosen, but our issue was (or at least that's what we were able to gather from several customers who faced this) that their firewall in the organization prevented connections to that domain. Unfortunately we don't use a CDN for our own site, but the idea behind was that serving it from our endpoint (which is under .microsoft.com) means that if they can access our site - they can fetch the fonts _[and if they can't access our site, the fonts don't matter anyway]_.
Just to recap then - our case was with firewalls of several customers of ours blocking (apparently?) .akamaihd.net (we also load the Segue UI font from .sharepointonline.com and that works fine for everybody). We moved them to be served from the static host that serves our other assets - images, js, css etc. So it's not a reliability issue we had with the default CDN, but a security-restriction one. If it was hosted elsewhere and would work for all of our customers, we would probably use the defaults - we obviously prefer not to maintain stuff we don't _need_ to.

Regarding your second question - whenever we updated office-ui-fabric-react (which may include an update to @uifabric/icons), we copy over the .woff files to our own /assets folder (see above - we serve them from our app's server) from @uifabric/icons's fonts folder - as you mentioned. Then just commit them to our source control. We could probably optimize this further, but it's good enough for now.

I'll check out the icon tool. Seems like a good idea, since we only need a few dozens of the 1700+ icons, as you mentioned.

[KevinTCoughlin]

@Jahnp is this resolved now that #7169 has been merged?

[Jahnp]

Hi @KevinTCoughlin and @bengry , very sorry for the delay. Between the US holidays and a few other obligations this fell off my radar--apologies!

@bengry: Gotcha, thank you for expanding on CDN issue you were encountering. That usage scenario makes perfect sense. For what it's worth, you should be able to swap out the Akamai endpoint with the sharepointonline.com one as the baseUrl (https://static2.sharepointonline.com/files/fabric/assets/icons/) to leverage the SPO CDN. This wasn't clear from any docs I could see, so I updated the Using Icons wiki page with a note about it.

We should probably just update the default base URL to point to the SharePoint one. We use the latter in a few other places as it is, and consistency for asset requests is always ideal--and if it plays nicer with firewalls, that's even better.

That said, if you still need to copy the .woff files for your custom CDN, #7169 adds the new font files to @uifabric/[email protected], which fixes the breaking change in 6.2.0--so you should be good to go. Let me know if you have any other issues/questions, otherwise I'll assume this issue is good to close.

Also, do let me know if you have any questions about the icons tool. If you're concerned about maintenance and performance, it has quite a few benefits over using the default icon set.

[bengry]

Thanks @Jahnp. We already copied the ones from 6.3.0, as mentioned.
We'll consider moving to the CDN the next time we visit this probably. We're also looking into the icon tool, as you mentioned.

Thanks for handling things quickly and providing solutions!
Closing this issue, as it's solved as far as I'm concerned.