It’s been a while since Rob Wormald from Google introduced the first web part using Angular Elements. Last week a new version 1.4.0 of the PnP SPFx Yeoman generator was released.

This new generator has some specifics that differs it from the other generators like Handlebars or VueJS. There were some considerations for the implementation of this new member in the SharePoint Framework family:

1. Angular developer love their CLI
2. Angular Elements directly integrate with SPFx can cause larger package sizes
3. An easy way to join to join to project together

Angular developer love their CLI

Nearly all framework these days come with their own CLI (command line interface) these days. Those CLIs helps people to set up and configure projects to their needs. Instead of knowing to modify this file there and add that reference there that CLIs offer much help to automate development tasks. Angular has its own CLI too, and Angular developer loves it. Integrate Angular Elements directly to a SharePoint Framework would have removed this possibility.

So how to make sure you can use the Angular CLI?

Instead of creating just one monolithic project that contains it creates two separate projects one for Angular Elements and on that wire up this project in a SharePoint Framework project.

Direct integration to SPFx vs separate project

Thanks to the base research by Andrew Connell that document his findings in his blog post series on using Angular Elements in SharePoint framework. He compared the approach of all in a single project versus the two project approach.

One big project containing everything removed as mentioned before the possibility to use the Angular CLI and a single web part would require the user to download 2.5 Megabyte.

A size way beyond acceptable especially for a mobile experience and at least doubtable for the desktop experience.

The two project approach, on the other hand, led to a more promising result of 330kb for a web part. Most of this file size comes from the Angular runtime, and the web part code is only a small portion inside this bundle.

This fact set the decision that this second approach is one we followed making a Yeoman generator for Angular Elements possible. So the two projects approach is excellent in case of performance and asset size but what is the downside on this?

The SharePoint Framework project needs to be aware of the Angular Elements project, or at least need to know that there is some external dependency.

Andrew Connell managed this by writing a custom bundle task that merges all required scripts and assets to a single file and copies the resulting bundle directly to the SPFX project.

In our setup, we followed a different approach.

An easy way to join to join to project together

Copy the resulting bundle of the Angular Project is a legitimate approach but every Angular Project is an NPM package too. The project root folder contains a ‘package.json’ that can serve as a dependency for any other NPM project.

When you execute ‘npm install’ for installing, for example, the PnP reusable components you always install the package from npmjs.com. There are more ways to you can install packages, this can be any Git repository or even from a local file path.

npm install <relative path to local package>

To install an Angular project named ‘hellong’ to a SharePoint Framework project the following command adds this reference:

npm install ../hellong

By doing so, the relative file path that can be found in the package.json of the SPFx project.

{
    "@microsoft/sp-webpart-base": "1.6.0",
    "@pnp/spfx-property-controls": "1.11.0",
    "@types/es6-promise": "0.0.33",
    "@types/webpack-env": "1.13.1",
    "hellong": "file:../hellong"
  },
  "devDependencies": {
    "@microsoft/sp-build-web": "1.6.0",
    ...
}

This reference exists in the node_modulesfolder but it is just a shortcut to the actual path. Similar to how the package manager ‘pnpm’ handles its dependencies. This way the “hellong” the SharePoint framework project treat the dependency like any other dependency on web parts and extensions.

import * as strings from 'HelloWorldWebPartStrings';

// reference to dist folder of ng bundle
import 'hellong/dist/hellong/bundle.js';

export interface IHelloWorldWebPartProps {
  description: string;
}

Every new build and bundle of the Angular Project automatically references the output correctly.

Welcome to Angular Elements in SPFx

A warm welcome to Angular Elements for SPFx, a generator Paweł Hawrylak built. Thank you very much for your contribution to this and the support in the forum.

Last but not least significant thanks to Andrew Connell that laid the foundation for this generator to happen.

Currently, this new generator is marked as experimental because we believe it is a great starting point for now, but we depend on your valuable feedback. If you have suggestions on how to improve this, please let us know on the issue list.

If you love what we are doing, please give us a star on GitHub to share your support.

If you like to help, us improve we are always open for new pull requests and check out the documentation too.

Also, check out the launch blog post.

Happy development with PnP/Spfx!

This post is a cross-post from MVP Article – PnP SPFx Yeoman generator v1.4.0 – Angular Elements support is here!