Helpers for building single-spa applications which use Angular.
See https://github.com/joeldenning/coexisting-angular-microfrontends.
If you're using the Angular CLI, use the Angular Schematic to quickly upgrade your application to single-spa.
In the root of your Angular CLI application run the following:
ng add single-spa-angular@betaThe schematic performs the following tasks:
- Install single-spa-angular.
- Create a new entry in the project's architect called
single-spa, which is a preconfigured Angular Builder. - Generate a
main.single-spa.tsin your project's/src. - Add an npm script
npm run build:single-spa.
Now create a file in the parent directory of your angular project called index.html. Your directory structure should look like this. Be sure to replace nameOfAngularProject with the actual name of your project.
index.html
nameOfAngularProject/
--> dist/
----> nameOfAngularProject/
------> main.js
--> package.json
--> angular.json
--> src/
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<title>Angular test</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
<base href="/" />
</head>
<body>
<script src="https://unpkg.com/single-spa/lib/umd/single-spa.min.js"></script>
<script src="https://unpkg.com/zone.js"></script>
<script src="/nameOfAngularProject/dist/nameOfAngularProject/main.js"></script>
<script>
singleSpa.registerApplication('nameOfAngularProject', window.nameOfAngularProject.default, location => true);
singleSpa.start();
</script>
</body>
</html>Finally, run the following command from inside of the application directory:
ng serve --openAlternatively you can run the following command from the root directory where your index.html is located:
npx light-server -s . --historyindex './index.html' -oCongrats! Now you've got your angular-cli application running as a single-spa application. Now you can add more Angular, React, or Vue applications to your root config's html file so that you have multiple microfrontends coexisting within a single page.
You can run ng build --prod, which will create a dist directory with your compiled code.
In root of the application run:
npm install --save single-spa-angularThen create main.single-spa.ts with the following content:
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { NgZone } from '@angular/core';
import singleSpaAngular from 'single-spa-angular';
import { Router } from '@angular/router';
import { AppModule } From './app/app.module';
export default singleSpaAngular({
bootstrapFunction: () => platformBrowserDynamic().bootstrapModule(AppModule),
template: `<component-to-render />`,
Router,
NgZone,
})
function domElementGetter() {
let containerEl = document.getElementById('my-app');
if (!containerEl) {
containerEl = document.createElement('div');
containerEl.id = 'my-app';
document.body.appendChild(containerEl);
}
return containerEl;
}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 returns a promise that resolves with a resolved Angular module that is bootstrapped. Usually, your implementation will look like this:bootstrapFunction: () => platformBrowserDynamic().bootstrapModule().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,<my-component />is recommended, but<div><my-component /><span>Hello</span><another-component /></div>is allowed. Note thatinnerHTMLis 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.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. Note that this opt can only be omitted when domElementGetter is passed in as a custom prop. So you must either dosingleSpaReact({..., domElementGetter: function() {return ...}})or dosingleSpa.registerApplication(name, app, activityFn, {domElementGetter: function() {...}})
- If you have multiple angular child applications, make sure that
reflect-metadatais only imported once in the root application and is not imported again in the child applications. Otherwise, you might see anNo NgModule metadata founderror. See issue thread for more details. - Note that you should only have one version of ZoneJS, even if you have multiple versions of Angular.
- Make sure that the root component selectors for each of your angular applications are unique so that angular can differentiate them. The default selector for an angular cli application is
app-root. You will need to update these selectors to be unique in your child application'sapp.component.ts, as well as in the singleSpaAngular template option found inmain.single-spa.ts. To catch other references (such as in test files) try a project wide find and replace forapp-root.
To aid in building your applications a builder is available to generate a module for single-spa to consume. NOTE: If you installed this library using the Angular Schematic, this is already configured.
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 > buildproperty. - Set the
builderproperty tosingle-spa-angular:build. - Run
ng buildand 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": {
"serveDirectory": "../"
}
}
}
}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 |
Configuration options are provided to the architect.serve.options section of your angular.json.
| Name | Description | Default Value |
|---|---|---|
| serveDirectory | (optional) A relative path to the directory where your index.html file is (single-spa root config) | "../" |
| singleSpaWebpackConfigPath | (optional) Path to partial webpack config to be merged with angular's config. Example: extra-webpack.config.js |
undefined |
For instructions on how to test this locally before creating a pull request, see the Contributing guidelines.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent