MVP Article - PnP SPFx Yeoman generator v1.4.0 - Angular Elements support is here!

It’s been a while since Rob Wormald from Google introduced the first SharePoint Framework client-side web part using Angular Elements and since Angular Elements was included in the Angular 6 release earlier this year, there was a clear demand for enabling it as an easy option also for SharePoint Framework developers.

Last week a new version 1.4.0 of the PnP SPFx Yeoman generator was released with a support of scaffolding SharePoint Framework solutions using Angular elements. Using Angular in SharePoint Framework has some specifics that differs it from the other generators like Handlebars or VueJS, so implementation differs slightly on those options.

There were some considerations for the implementation of this new member in the SharePoint Framework family:

Angular developer love their CLI
Angular Elements directly integrate with SPFx can cause larger package sizes
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 developers love 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, PnP SPFx Yeoman generator creates two separate projects: one for Angular Elements and second for the SharePoint Framework solution, which is then linked to the Angular project.

Direct integration to SPFx vs separate project

Thanks to the base research by Andrew Connell (Voitanos) 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.

That’s beyond a bundle size 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 great 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 then 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_modules` folder 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. Also big 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, we are always open to new pull requests and check out the documentation too.

Also, check out the launch blog post.

Happy development with PnP SPFx Yeoman generator!

About the Author

Stefan Bauer is an information architect, Microsoft Office Development MVP and part of the Pattern and Practice core team based in Austria. He is also leading the open-source PnP/SPFx yeoman generator project that helps developers to extend the features to their requirements.