SharePoint Framework and Angular - Walkthrough of the SPFx Angular Boilerplate

In this post, we will cover the general concepts used to make the SharePoint Framework Angular Boilerplate work and how it solves the challenges that were preventing the production use of both technologies together.

This post is part of a series that contains the following posts :

  • SharePoint Framework and Angular - Introducing the SPFx Angular Boilerplate
  • SharePoint Framework and Angular - Walkthrough of the SPFx Angular Boilerplate (this post)
  • SharePoint Framework and Angular - Build your first webpart (coming soon...)
  • SharePoint Framework and Angular - Build your second webpart (coming soon...)
  • SharePoint Framework and Angular - Contribute and provide feedback (coming soon...)

Getting Angular in the project

First of all, we had to add Angular to the project. As you can see in the package.json, we added all the Angular related modules and its dependencies.

Fixing some complaints of the bundling process

Then, some complaints from the webpack bundler started to happen during the bundling process of the project. We had to add a setting to the tsconfig.json file to skip the library check. That prevents TypeScript transpilation error and will "assume" that all the libraries are valid. The resulting tsconfig.json is the following.

Then, we have to instruct webpack of where the application source files are located. That was done through the gulpfile.js. Adding the ContextReplacementPlugin was necessary to fix the request dependency bug in Angular 5644:15-36 Critical dependency: the request of a dependency is an expression. The resulting gulpfile.js is the following.

The last piece that needs to happen is to externalize the Zone.js component of the bundle. This is EXTREMELY IMPORTANT. Without this, the code will work without any problem but will break as soon as another webpart built with Angular but from another project will be dropped on the same page as yours. The key to this boilerplate is to keep a single Zone.js instance to be loaded so all the webparts share the same.

To do that, we had to modify the config\config.json file and add the following to the externals section.

The project is now ready to build webparts using Angular as everything will be bundled and will allow multiple webparts, multiple instances of the same webparts and multiple webparts from multiple projects!

Using the BaseAngularWebPart

There is a lot of magic happening in the BaseAngularWebPart. This class is responsible for 3 major things. First of all, it renders the webparts by specifying its "DOM" element to be dynamic for every webpart instance running. The following snippet highlights this method.

Then, once the "DOM" element is rendered, we want to bootstrap our NgModule to take over and render the actual set of components. The following snippet does it using the Zone.js component and dos a dynamic bootstrapping of our module.

Finally, we need to find the Root Component that will be used and create the NgModule with all its required settings and dependencies. The actual SharePoint Framework WebPart will instruct the BaseAngularWebPart of which of the set of components is the Root Component, which are the Providers, which are the Sub Components and what are the Routes to bundle in the Application.

With that class, any SharePoint Framework WebPart can be coded using a set of Angular components.

Inheriting from the BaseAngularWebPart

The only requirement is to inherit from the BaseAngularWebPart and to instruct the Framework of some of the required elements to be used within the previous logic. First of all, it is required to inherit from the BaseAngularWebPart and specify in there what will be the base Application Component.

Then, we need to return a set of properties that will be used by the BaseAngularWebPart abstract class so it can build a proper NgModule. You will not be able to build your WebPart without those as they are abstract methods to override.

Configuring your routes

To use a generic approach for your components and be as isolated from the SharePoint Framework as possible, the management of components (what to load when) is done through the Angular routing system. Providing the routing ahead of time will allow us to not only have a great navigation between components, but also to write all of our components with Angular code only. Nothing in the components will have a reference to the SharePoint Framework because of that.

Creating your Application Component

Finally, the only missing piece is the Root Application Component that has to be created and that is an empty component with a simple router outlet. That will allow us to have a full routing system that manages our components and will keep our Angular code totally separated from the SharePoint Framework code.

Video Walkthrough

What's next?

That's it? It's that "simple"? Well... Surprisingly, it was not that much complex to get it working and the result is exactly what we're looking for : Coding Angular Components in a SharePoint Framework Webpart!

In the next post, we will create your first SharePoint Framework Solution using Angular!

Oh! And (finally), happy Angular coding on the SharePoint Framework!