id: ecosystem-angular title: single-spa-angular
sidebar_label: Angular
Introduction
single-spa-angular is a library for creating Angular microfrontends.
Each microfrontend (single-spa application) is an Angular CLI project that can use its own version of Angular and be deployed separately from any other. They all come together into a single web page where one or more single-spa applications is active at any time.
The documentation here is extensive, so use the sidenav on the right. 👉👉👉
Community
Join the #angular
channel in single-spa’s slack workspace.
Demo
https://coexisting-angular-microfrontends.surge.sh
Starter repo
https://github.com/joeldenning/coexisting-angular-microfrontends
Contributing
For instructions on how to test this locally before creating a pull request, see the Contributing docs.
Angular versions
Angular 1 (AngularJS)
AngularJS is supported by single-spa-angularjs, instead of single-spa-angular. See AngularJS docs.
Angular 2
Angular 2 is supported by single-spa-angular@3.
The single-spa-angular schematics are not supported by Angular 2, so you’ll have to follow the steps for manual installation. The single-spa helpers work with Angular 2.
Angular 3
Angular 3 never existed.
Angular 4
Angular 4 is supported by single-spa-angular@3.
The single-spa-angular schematics are not supported by Angular 4, so you’ll have to follow the steps for manual installation. The single-spa helpers work with Angular 4.
Angular 5
Angular 5 is supported by single-spa-angular@3.
The single-spa-angular schematics are not supported by Angular 5, so you’ll have to follow the steps for manual installation. The single-spa helpers work with Angular 5.
Angular 6
Angular 6 is supported by single-spa-angular@3.
The single-spa-angular schematics are not supported by Angular 6, so you’ll have to follow the steps for manual installation. The single-spa helpers work with Angular 6.
Angular 7
Angular 7 is supported by single-spa-angular@3.
Both the single-spa-angular schematics and the single-spa helpers work with Angular 7. Follow the Angular CLI instructions.
Note that the schematics for Angular 7 use an Angular Builder that is no longer used in the Angular 8 schematics.
Angular 8
Angular 8 is supported by single-spa-angular@3.
Both the single-spa-angular schematics and the single-spa helpers work with Angular 8. Follow the Angular CLI instructions.
Note that the schematics for Angular 8 do not use the custom Angular builder, but instead use @angular-builders/custom-webpack.
Angular 9
Angular 9 is supported by single-spa-angular@4.
Both the single-spa-angular schematics and the single-spa helpers work with Angular 9. Follow the Angular CLI instructions.
Note that the schematics for Angular 9 do not use the custom Angular builder, but instead use @angular-builders/custom-webpack.
Angular CLI
You may use Angular CLI and single-spa together with any version of Angular. However, the Angular CLI schematics only work if you’re using Angular >= 7. If you’re using an older version of Angular, follow the manual installation instructions.
Installation
First, create an angular application. This requires installing Angular CLI. Note that the --prefix
is important so that when you have multiple angular applications their component selectors won’t have the same names.
ng new my-app --routing --prefix my-app
cd my-app
In the root of your Angular CLI application run the following:
ng add single-spa-angular
Schematics
Angular schematics are processed when you run ng add single-spa-angular
.
The single-spa-angular schematics perform the following tasks:
- Install single-spa-angular.
- Generate a
main.single-spa.ts
in your projectsrc/
. - Generate
single-spa-props.ts
insrc/single-spa/
- Generate
asset-url.ts
insrc/single-spa/
- Generate an EmptyRouteComponent in
src/app/empty-route/
, to be used in app-routing.module.ts. - Add an npm script
npm run build:single-spa
. - Add an npm script
npm run serve:single-spa
. - For Angular 7 only, create a new entry in the project’s architect called
single-spa
, which is a preconfigured Angular Builder.
Finish installation
Now you must configure routes. Then you can serve and build.
Manual Installation
The manual installation instructions should be used if you are not using Angular CLI or if you are using Angular 6 or older.
Installation
npm install --save single-spa-angular
Manually apply schematics
Since the single-spa-angular schematics didn’t run, you’ll need to make the following changes:
- Create all of the files that would have been created by the schematic. See schematics files. Be sure to get the files in the subdirectories, too.
- Add
build:single-spa
andserve:single-spa
to the scripts in your package.json. SeeaddNPMScripts
function. - Use the angular builder, as described in the next section.
Use Angular Builder
Note that this only applies to Angular versions pre Angular 8. Up until Angular 8, we maintained an angular builder that allowed us to control the webpack config, but since Angular 8 we use @angular-builders/custom-webpack instead. See documentation for using the custom webpack builder with single-spa-angular and Angular 8+.
If you installed this library with Angular 7 using the Angular Schematic, this is already configured and you don’t need to change it. Otherwise, you might need to do this manually.
If you don’t use Angular CLI, skip this section.
To build your Angular CLI application as a single-spa app do the following.
- Open
angular.json
- Locate the project you wish to update.
- Navigate to the
architect > build
property. - Set the
builder
property tosingle-spa-angular:build
. - Run
ng build
and verify your dist contains one asset,main.js
.
Example Configuration:
{
"architect": {
"build": {
"builder": "single-spa-angular:build",
"options": {
"libraryName": "hello",
}
},
"serve": {
"builder": "single-spa-angular:dev-server",
"options": {
}
}
}
}
ng build options
Configuration options are provided to the architect.build.options
section of your angular.json.
Name | Description | Default Value |
---|---|---|
libraryName | (optional) Specify the name of the module | Angular CLI project name |
libraryTarget | (optional) The type of library to build see available options | “UMD” |
singleSpaWebpackConfigPath | (optional) Path to partial webpack config to be merged with angular’s config. Example: extra-webpack.config.js |
undefined |
ng serve options
Configuration options are provided to the architect.serve.options
section of your angular.json.
Name | Description | Default Value |
---|---|---|
singleSpaWebpackConfigPath | (optional) Path to partial webpack config to be merged with angular’s config. Example: extra-webpack.config.js |
undefined |
Use Custom Webpack
Starting with Angular 8, single-spa-angular’s schematics install and use @angular-builders/custom-webpack
to modify the webpack config. The schematics also create an extra-webpack.config.js
file in your project where you can modify the configuration further.
The extra-webpack.config.js file should include the following:
const singleSpaAngularWebpack = require('single-spa-angular/lib/webpack').default;
module.exports = (config, options) => {
const singleSpaWebpackConfig = singleSpaAngularWebpack(config, options);
// Feel free to modify this webpack config however you'd like to
return singleSpaWebpackConfig;
};
Older versions of single-spa-angular@3 and single-spa-angular@4 created extra-webpack.config.js files that did not pass options
into singleSpaAngularWebpack
. When you upgrade to newer versions, you’ll need to pass in the options as shown above.
In addition to modifying the webpack config directly, you may alter some of single-spa-angular’s behavior by changing the angular.json. Configuration options are provided to the architect.build.options.customWebpackConfig
section of your angular.json.
Name | Description | Default Value |
---|---|---|
path | (required) Path to the the above extra-webpack.config.js file. |
N/A |
libraryName | (optional) Specify the name of the module | Angular CLI project name |
libraryTarget | (optional) The type of library to build see available options | “UMD” |
If you’re using SystemJS, you may want to consider changing the webpack output.libraryTarget to be "system"
, for better interop with SystemJS.
Routing
Configure routes
To get single-spa working, you’ll need to manually modify a few files.
- Add
providers: [{ provide: APP_BASE_HREF, useValue: '/' }]
toapp-routing.module.ts
. See angular docs for more details about APP_BASE_HREF. - Add
{ path: '**', component: EmptyRouteComponent }
to yourapp-routing.module.ts
routes. The EmptyRouteComponent is part of the single-spa-angular schematics. This route makes sure that when single-spa is transitioning between routes that your Angular application doesn’t try to show a 404 page or throw an error. See angular docs for more details about routes. - Add a declaration for EmptyRouteComponent in
app.module.ts
. See angular docs for more details about app.module.ts.
Note
APP_BASE_HREF should have the same value that the used url for mount the Angular app defined in the single-spa root application. But doing this causes strange behaviours in Angular Router when navigate between registered apps.
In order to avoid this is recommended using ‘/‘ as APP_BASE_HREF and repeat the url prefix for your Angular app in every route component and router links. If you set /angular in your Angular app activity function for mount when the url starts with this value you’ll have to add /angular prefix in all links.
You can see several discussions about this issue in single-spa-angular GitHub repo: Router not working without APP_BASE_HREF and How to handle router links between different single-spa application subrouters
Linking between applications
To link between applications, simply use routerLink
like normal.
<a routerLink="/other-app">
Link to other app
</a>
Nested routes
Nested routes work exactly the same as they normally do. To create a nested route, add it to your app-routing.module.ts.
To link to a nested route, use routerLink
the same way you normally do.
<a routerLink="/my-app/nested-route">
Link to nested route
</a>
Serving
Run the following:
npm run serve:single-spa
This will not open up an HTML file, since single-spa applications all share one html file. Instead, go to http://single-spa-playground.org and follow the instructions there to verify everything is working and for instructions on creating the shared HTML file.
Building
Run npm run build:single-spa
, which will create a dist
directory with your compiled code.
In order for the webpack public path to be correctly set for your assets, you should use Angular CLI’s --deploy-url
option. For more information, see this Stack Overflow answer which shows a few options for how to do that.
The single-spa helpers
Introduction
“single-spa helpers” refers to the in-browser portion of single-spa-angular. The helpers are used by all versions of Angular and regardless of whether you are using Angular CLI or not. This is the core of the single-spa-angular library that makes it possible for Angular applications to bootstrap, mount, and unmount. See single-spa lifecycles for more information.
Migrating from single-spa-angular@3.x to single-spa-angular@4.x
Migrating from 3.x to 4.x requires only few API updates.
Packages
npm i --save single-spa-angular@4.0.0
# Or if you're using yarn
yarn add single-spa-angular@4.0.0
API Updates
single-spa-angular
doesn’t have a default export anymore, instead you have to import a named singleSpaAngular
function. Given the following code:
import singleSpaAngular from 'single-spa-angular'; // single-spa-angular@3.x
import { singleSpaAngular } from 'single-spa-angular'; // single-spa-angular@4.x
Also, if your application uses routing then you have to import the getSingleSpaExtraProviders
function. Let’s look at the following example, this is how it was in single-spa-angular@3.x
:
import { NgZone } from '@angular/core';
import { Router } from '@angular/router';
import singleSpaAngular, { getSingleSpaExtraProviders } from 'single-spa-angular';
const lifecycles = singleSpaAngular({
bootstrapFunction: singleSpaProps => {
singleSpaPropsSubject.next(singleSpaProps);
return platformBrowserDynamic(getSingleSpaExtraProviders()).bootstrapModule(AppModule);
},
template: '<app-root />',
Router,
NgZone,
});
And this is how it should be in single-spa-angular@4.x
:
import { NgZone } from '@angular/core';
import { Router } from '@angular/router';
import { singleSpaAngular, getSingleSpaExtraProviders } from 'single-spa-angular';
const lifecycles = singleSpaAngular({
bootstrapFunction: singleSpaProps => {
singleSpaPropsSubject.next(singleSpaProps);
return platformBrowserDynamic(getSingleSpaExtraProviders()).bootstrapModule(AppModule);
},
template: '<app-root />',
Router,
NgZone,
});
Basic usage
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { NgZone } from '@angular/core';
import { Router } from '@angular/router';
import { singleSpaAngular, getSingleSpaExtraProviders } from 'single-spa-angular';
import { AppModule } from './app/app.module';
const lifecycles = singleSpaAngular({
bootstrapFunction: singleSpaProps => {
return platformBrowserDynamic(getSingleSpaExtraProviders()).bootstrapModule(AppModule);
},
template: '<app-root />',
Router,
NgZone,
});
export const bootstrap = lifecycles.bootstrap;
export const mount = lifecycles.mount;
export const unmount = lifecycles.unmount;
Full Example
See this schematic file for a good example of how to use the single-spa helpers.
Options
Options are passed to single-spa-angular via the opts
parameter when calling singleSpaAngular(opts)
. This happens inside of your main.single-spa.ts
file.
The following options are available:
bootstrapFunction
: (required) A function that is given custom props as an argument and returns a promise that resolves with a resolved Angular module that is bootstrapped. Usually, your implementation will look like this:bootstrapFunction: (customProps) => platformBrowserDynamic().bootstrapModule()
. See custom props documentation for more info on the argument passed to the function.template
: (required) An HTML string that will be put into the DOM Element returned bydomElementGetter
. This template can be anything, but it is recommended that you keeping it simple by making it only one Angular component. For example,<app-root />
is recommended, but<div><app-root /><span>Hello</span><another-component /></div>
is allowed. Note thatinnerHTML
is used to put the template onto the DOM. Also note that when using multiple angular applications simultaneously, you will want to make sure that the component selectors provided are unique to avoid collisions. When migrating to single-spa, this template is what is inside of your index.html file’s<body>
element.Router
: (optional) The angular router class. This is required when you are using@angular/router
.AnimationModule
: (optional) The animation module class. This is required when you are using BrowserAnimationsModule. Example way to import this:import { eAnimationEngine as AnimationModule } from '@angular/animations/browser';
. See Issue 48 for more details.domElementGetter
: (optional) A function that takes in no arguments and returns a DOMElement. This dom element is where the Angular application will be bootstrapped, mounted, and unmounted. It’s recommended to omit this and let single-spa-angular’s defaults create and use a container div.
Concepts
ZoneJS
ZoneJS is the library that Angular uses for change detection. You absolutely must have exactly one instance of the ZoneJS library on the page. ZoneJS will throw errors if you have more than one instance of ZoneJS on the page.
The preferred way to ensure only one instance of ZoneJS is loaded on your page is with a script tag in your root-config’s HTML file. You should load ZoneJS upfront a single time, before loading SystemJS or any of your microfrontends.
<script src="https://cdn.jsdelivr.net/npm/zone.js@0.10.3/dist/zone.min.js"></script>
Note that having only one instance of ZoneJS is different than having only one zone within that instance. single-spa-angular automatically will ensure that each of your Angular applications has its own isolated, separate zone.
Multiple applications
When you have multiple apps running side by side, you’ll need to make sure that their
component selectors are unique. When creating a new
project, you can have angular-cli do this for you by passing in the --prefix
option:
ng new --prefix app2
If you did not use the --prefix
option, you should set the prefix manually:
- For an application called app2, add
"prefix": "app2"
toprojects.app2
inside of the angular.json. - Go to
app.component.ts
. Modifyselector
to beapp2-root
. - Go to
main.single-spa.ts
. Modifytemplate
to be<app2-root>
.
Additionally, make sure that reflect-metadata
is only imported once in the root application and is not imported again in the child applications.
Otherwise, you might see an No NgModule metadata found
error.
See issue thread for more details.
Custom Props
Custom props are a way of passing auth or other data to your single-spa applications. The custom props are available inside of the bootstrapFunction passed to singleSpaAngular(). Additionally, if you use the angular cli schematic, you may subscribe to the singleSpaPropsSubject in your component, as shown below:
// An example showing where you get access to the single-spa props:
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { singleSpaAngular } from 'single-spa-angular';
const lifecycles = singleSpaAngular({
bootstrapFunction(singleSpaProps) {
// Here are the custom props
console.log(singleSpaProps);
return platformBrowserDynamic().bootstrapModule(AppModule);
},
// add the other options to singleSpaAngular, too. See "Basic usage" for more info
})
// If you're using the singleSpaPropsSubject generated by the single-spa-angular schematics,
// here's an example component that uses the custom props
import { Component, OnInit, OnDestroy } from '@angular/core';
import { Subscription } from 'rxjs';
import { singleSpaPropsSubject, SingleSpaProps } from 'src/single-spa/single-spa-props';
@Component({
selector: 'app-root',
templateUrl: './app.component.html',
styleUrls: ['./app.component.css'],
})
export class AppComponent implements OnInit, OnDestroy {
singleSpaProps: SingleSpaProps;
subscription: Subscription;
ngOnInit(): void {
this.subscription = singleSpaPropsSubject.subscribe(
props => (this.singleSpaProps = props),
);
}
ngOnDestroy(): void {
this.subscription.unsubscribe();
}
// OR if you don't need to access `singleSpaProps` inside the component
// then create `Observable` property and use it in template with `async` pipe.
singleSpaProps$ = singleSpaPropsSubject.asObservable();
}
Angular assets
Angular assets are handled differently within single-spa than within
other Angular applications. The schematics file called asset-url.ts
helps you do load assets in a way that works both ways.
This won’t work
// Doesn't work with single-spa
const imageUrl = '/assets/yoshi.png';
Do this instead
import { assetUrl } from 'src/single-spa/asset-url';
// Works great with single-spa
const imageUrl = assetUrl('yoshi.png')
Within HTML templates
Option 1
Add the asset url to your component’s class and reference it from the template. See here and here.
Option 2
Create an Angular Pipe that lets you calculate the asset url inside of an HTML template:
import { Pipe, PipeTransform } from '@angular/core';
import { assetUrl } from 'src/single-spa/public-path';
@Pipe({ name: 'assetUrl' })
export class AssetUrlPipe implements PipeTransform {
transform(value: string): string {
return assetUrl(value);
}
}
Then use it in your template:
<img [src]="'yoshi.png' | assetUrl" />
Scripts
Scripts in your angular.json are not loaded by single-spa. This is because single-spa applications have to all share an HTML file. (read more). You can remove the scripts from your angular.json because they have no impact on your single-spa build.
Option 1
Add the script tags directly into your root HTML file. This way is easiest. The downside is that all of the scripts get loaded even for routes that don’t need them. However, that is generally okay and this is the preferred way to do it.
Option 2
If you want the scripts to only be loaded when needed, you can add a custom bootstrap lifecycle to your code.
Note that lazy loading these scripts can actually be worse for performance if you always need them, since they will start downloading later than if you put them right into the root HTML file.
// main.single-spa.ts
// Modify the bootstrap function like so
export const bootstrap = [
() => Promise.all([
loadScript('https://cdnjs.cloudflare.com/ajax/libs/jquery/3.4.1/jquery.min.js'),
loadScript('https://cdnjs.cloudflare.com/ajax/libs/datepicker/0.6.5/datepicker.min.js'),
]),
lifecycles.bootstrap,
]
function loadScript(url: string) {
return new Promise((resolve, reject) => {
const script = document.createElement('script');
script.src = url;
function onLoad() {
resolve();
cleanup();
}
function onError(event: Event) {
reject(event);
cleanup();
}
function cleanup() {
script.removeEventListener('load', onLoad);
script.removeEventListener('error', onError);
}
script.addEventListener('load', onLoad);
script.addEventListener('error', onError);
document.head.appendChild(script);
});
}
Styles
Styles in your angular.json will automatically be loaded by single-spa-angular’s webpack config, without you having to configure anything.
Your component styles will also be loaded like normal without you having to configure anything.
rebaseRootRelativeCssUrls
The rebaseRootRelativeCssUrls option allows you to keep your css referencing asset urls, which will be rewritten to respect the webpack public path:
.body-row {
background: url("/assets/images/person.jpg") no-repeat right bottom;
}
To do this, you may change your angular.json or run ng build --rebaseRootRelativeCssUrls
. In the angular.json file, you should modify
architect > build > options and update the property rebaseRootRelativeCssUrls
to be true
.
Now inside the assets attribute (which is an array) you should add a slash “/“ to the value of the “output” attribute which outputs its external styles (this is optional). Example:
{
"options": {
"rebaseRootRelativeCssUrls": true,
"assets": [
"src/favicon.ico",
"src/assets",
{
"glob": "**/*",
"input": "node_modules/@material/dist/collection/assets",
"output": "/assets"
}
]
}
}
Polyfills
Polyfills in your angular.json are JavaScript code that make your project work in older browsers, such as IE11.
The polyfills that you specify in your angular.json file will not be loaded automatically. This is because we should only load polyfills once in the root HTML file, instead of once per application.
To load polyfills, you’ll need to follow the instructions in the Angular documentation for non-CLI users. Even if you are using Angular CLI, you will need to follow those instructions, since your single-spa root HTML file is not using Angular CLI and that’s where the polyfills need to go.
If you’re looking for a quick one-liner, try adding this line near the top of your index.html.
<script src='https://unpkg.com/core-js-bundle/minified.js'></script>
Internet Explorer
If you need to support IE11 or older, do the following:
- Add core-js polyfill
- Remove arrow functions from index.html (example)
- Change angular.json
target
toes5
(example)
Full example commit to get IE11 support
Angular Elements
⚠️ This feature is available starting from
single-spa-angular@4.4.0
. You also may need to become familiar with Angular Elements documentation.
Let’s start with installing the @angular/elements
:
npm i --save @angular/elements
# Or if you're using yarn
yarn add @angular/elements
The next step is to edit main.single-spa.ts
:
import { enableProdMode } from '@angular/core';
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { singleSpaAngularElements } from 'single-spa-angular/elements';
import { AppModule } from './app/app.module';
import { environment } from './environments/environment';
if (environment.production) {
enableProdMode();
}
const lifecycles = singleSpaAngularElements({
template: '<app-custom-element />',
// We can actually not rely on the `zone.js` library, our custom element
// will behave itself as a zone-less application.
bootstrapFunction: () => platformBrowserDynamic().bootstrapModule(AppModule, { ngZone: 'noop' }),
});
export const bootstrap = lifecycles.bootstrap;
export const mount = lifecycles.mount;
export const unmount = lifecycles.unmount;
Note that the app-custom-element
selector will be used when defining our custom element.
After that, you’ll have to edit app.module.ts
and define a custom tag:
import { NgModule, Injector, DoBootstrap } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { createCustomElement } from '@angular/elements';
import { AppComponent } from './app.component';
@NgModule({
imports: [BrowserModule],
declarations: [AppComponent],
})
export class AppModule implements DoBootstrap {
constructor(private injector: Injector) {}
ngDoBootstrap(): void {
customElements.define(
// This tag we've have provided in `options.template` when called `singleSpaAngularElements`.
'app-custom-element',
createCustomElement(AppComponent, { injector: this.injector }),
);
}
}
The following options are available to be passed when calling singleSpaAngularElements
:
bootstrapFunction
(required)template
(required)domElementGetter
(optional)
See options for detailed explanation.
Advanced
Zone-less applications
⚠️ This feature is available starting from
single-spa-angular@4.1
.
It’s possible to develop Angular applications that don’t rely on zone.js
library, these applications are called zone-less. You have to run change detection manually in zone-less applications through ApplicationRef.tick()
or ChangeDetectorRef.detectChanges()
. You can find more info in Angular NoopZone docs.
The point is that you do not need to load zone.js
library in your root HTML file. As Angular docs mention that you should have a comprehensive knowledge of change detection to develop such applications. Let’s start by nooping zone when bootstrapping module:
import { singleSpaAngular } from 'single-spa-angular';
const lifecycles = singleSpaAngular({
bootstrapFunction: () =>
platformBrowserDynamic().bootstrapModule(AppModule, { ngZone: 'noop' }),
template: '<app-root />',
NgZone: 'noop',
});
💡 Note, that we have to specify
noop
2 times: when bootstrappingAppModule
and settingNgZone
property tonoop
, thus we tell Angular and single-spa-angular that we’re not going to use zones.
Routing in zone-less applications
Since routing is managed by single-spa and there is no zone that tells Angular that some asynchronous event has occured, then we need to tell Angular when to run change detection if routing occurs. Let’s look at the below code:
import { ApplicationRef } from '@angular/core';
import { Router } from '@angular/router';
import { singleSpaAngular } from 'single-spa-angular';
const lifecycles = singleSpaAngular({
bootstrapFunction: async () => {
const ngModuleRef = await platformBrowserDynamic().bootstrapModule(
AppModule,
{ ngZone: 'noop' },
);
const appRef = ngModuleRef.injector.get(ApplicationRef);
const listener = () => appRef.tick();
window.addEventListener('popstate', listener);
ngModuleRef.onDestroy(() => {
window.removeEventListener('popstate', listener);
});
return ngModuleRef;
},
template: '<app-root />',
NgZone: 'noop',
Router,
});
⚠️
single-spa-angular@4.x
requires callinggetSingleSpaExtraProviders
function in applications that have routing. Do not call this function in zone-less application.