This post is long, LONG overdue. I’ve explained this multiple times over email & in person to SharePoint Framework developers. It’s about time I have something to point to… so here’s my take on the SharePoint Framework + Angular [v2.0 / v4.0 / v+] state of things.
Have you tried to build a client-side web part using the SharePoint Framework using something other than ReactJS? Maybe you prefer using Angular over React… I know I do! While using AngularJS to create SPFx solutions is fairly straightforward, using Angular is a bit more complicated.
This confuses folks quite a bit but it’s actually quite simple. You’ve likely heard of Angular 1… when we say “AngularJS” we mean everything in the version 1.x branch. Then there was a major update to Angular in going from v1 to v2 and along with this, the team at Google wanted to move away from the old versioning scheme and instead adopt a semver versioning approach. They opted for a scheduled release plan where new major versions were released every 6 months. This is very similar to how popular open source projects like Docker & Node.js do it.
Around the same time, they decided to rename the framework to Angular which is supposed to represent all versions of Angular v2 and higher. So… when you say Angular, you really mean everything after v1. When you need to get specific, like at times the Angular team does, you’ll see them refer to it as a version with something like Angular v5 or Angular 5.0 (which we should see any day now). These updates from one major version are in fact usually very minor… they typically haven’t included some epic breaking changes.
I do wish the Angular team would post a succinct “here’s what’s up with our naming scheme” article on their docs sites… but for now, this blog post does the best job of explaining it… including why v3 was skipped.
In the context of this post, when I say Angular, I’m referring to Angular v4.0 or higher… including v5.0 which we should see any day now.
So… back to the original question:
I want to build a client-side web part with the SharePoint Framework using Angular [v4.0]… what’s the current state of that?
I get this question quite a bit from customers of my Mastering the SharePoint Framework course. There are a few good posts that show you how to do it, but today, like Waldek’s & Sebastien’s, but from my point of view, I’d avoid it for now.
Avoid it for now… but why?
First, let me be as clear as I can: this is not a Microsoft or SharePoint Framework problem. This challenge is due to the way Angular has been architected with the assumption that it will be the only framework on the page and own the entire page. There is literally nothing Microsoft can do with SPFx to alleviate this pain you have.
Angular, unlike its v1.x predecessor, is architected from the core to own the entire page. This was done for performance reasons and it works quite well. To do this, there’s a single parent component on the page that contains all other Angular components on the page. This tree model is quite performant and makes for a great framework.
But where it presents challenges is when the developer doesn’t own the page, such as a composable page. SharePoint is one of these such cases.
In the context of SharePoint, I can build a web part with Angular and let someone put it on the page, but if someone adds another Angular-authored web part to the page, the model breaks down as there’s no one component on the page that owns everything.
Most developers I see venture down this path building and testing their Angular web part in a silo and don’t try other Angular web parts (or the same one added multiple times) to the page, leading to a production “uh oh” experience.
The two blog posts I reference above by Waldek & Sebastien talk about this challenge and how to avoid it. Their solutions are to dynamically create a top-level component on the page that all other Angular components are added to. This makes it work, but as great as this solution is, it isn’t ideal.
One reason they aren’t ideal is that one feature introduced Angular v4.0 is Ahead-of-Time Compilation (AOT). AOT is something you’d run on your Angular project before you push it to production. What it does is pre-compile your project and, along with tree shaking, all the Angular code you aren’t using is removed from the final deployment. Without this, you’re looking at a large (~1MB+) JavaScript bundle for your SPFx client-side web part.
So why not just run AOT & tree shaking on the SPFx Angular v4.0 client-side web part?
Because you can’t… you can’t because all the solutions mentioned above dynamically create the root component. AOT involves static code analysis and therefore, you can’t mix the two.
So today, if you want to use Angular v4.0 or higher to build an SPFx client-side web part, you have two options:
Somehow ensure you are the only Angular client-side web part on the page, and somehow keep your users from adding a second (either the same client-side web part or a different one).
Good luck with this approach… I don’t advise this…
Use the dynamic root component approach that Sebastien’s post I linked to above demonstrates. The downside here is you’ll likely have a fairly large bundle (500kb minimum) you’re deploying to the page. Sure… it works, but every web developer atom in you should cringe at that.
Wait… That’s It?
Seriously? That’s the end of the story?
Sort of… but just for now that’s the current state of Angular & the SharePoint Framework.
Rest assured… Google & and Angular team is well aware of this. This challenge with Angular affects not just those of us in the SharePoint Framework development space, but many others. They are actively working to make things better.
For now… just sit tight. In a few weeks, there’s likely going to be some very good news on this topic. I’m privy to the approach they are taking and it’s VERY appealing… not just for SPFx developers, but it makes Angular significantly more appealing on various levels!
Stay tuned to this blog as I’ll have an update on this when there is more to share.
