single-spa

What is single-spa?

single-spa is a JavaScript framework for front-end microservices. It allows you to build and manage multiple microfrontends that can coexist and interoperate within a single web application. This enables teams to work independently on different parts of a web application, using different frameworks if necessary.

What are single-spa's main functionalities?

Registering Applications

This feature allows you to register multiple applications with single-spa. Each application can be loaded dynamically and activated based on the URL path.

const singleSpa = require('single-spa');
singleSpa.registerApplication({
  name: 'app1',
  app: () => System.import('app1'),
  activeWhen: ['/app1'],
  customProps: {}
});
singleSpa.start();

Mounting and Unmounting Applications

This feature allows you to manually mount and unmount applications, giving you fine-grained control over which applications are active at any given time.

const singleSpa = require('single-spa');
singleSpa.registerApplication({
  name: 'app2',
  app: () => System.import('app2'),
  activeWhen: ['/app2'],
  customProps: {}
});
singleSpa.start();

// Manually mount an application
singleSpa.mountRootParcel('app2', { domElement: document.getElementById('app2-container') });

// Manually unmount an application
singleSpa.unmountRootParcel('app2');

Custom Events

This feature allows you to dispatch and listen for custom events, enabling communication between different microfrontends.

const singleSpa = require('single-spa');
singleSpa.registerApplication({
  name: 'app3',
  app: () => System.import('app3'),
  activeWhen: ['/app3'],
  customProps: {}
});
singleSpa.start();

// Dispatch a custom event
window.dispatchEvent(new CustomEvent('custom-event', { detail: { someData: 'data' } }));

// Listen for a custom event
window.addEventListener('custom-event', (event) => {
  console.log(event.detail.someData);
});

Other packages similar to single-spa

qiankun

qiankun is a micro-frontend framework based on single-spa. It provides additional features like sandboxing and lifecycle hooks, making it easier to manage microfrontends in complex applications.

mooa

mooa is a micro-frontend framework inspired by single-spa. It focuses on Angular applications and provides a simpler API for integrating multiple Angular microfrontends.

icestark

icestark is a micro-frontend framework developed by Alibaba. It offers a set of tools and conventions for building and managing microfrontends, with a focus on React and Vue applications.

README

single-spa

Join the chat on Slack

A javascript metaframework

Build micro frontends that coexist and can each be written with their own framework. This allows you to:

• Use multiple frameworks on the same page without refreshing the page (React, AngularJS, Angular, Ember, or whatever you're using)
• Write code using a new framework, without rewriting your existing app
• Lazy load code for improved initial load time.

Demo and examples

A live demo is available and the source code for that demo is available in the single-spa-examples repository.

Also, you can check out a simple webpack starter project which is simpler and hopefully easier to get started with.

Architectural Overview

Single-spa takes inspiration from React component lifecycles by applying lifecycles to entire applications. It started out of a desire to use React + react-router instead of being forever stuck with our AngularJS + ui-router application, but now single-spa supports almost any framework coexisting with any other. Since Javascript is notorious for the short-life of its many frameworks, we decided to make it easy to use whichever frameworks you want.

Apps built with single-spa are made up of the following pieces:

1. Many applications, each of which is sort of like an entire SPA itself. Applications respond to url routing events and must know how to bootstrap, mount, and unmount themselves from the DOM. The main difference between a SPA and an application is that applications must coexist together and do not each have their own html page. For example, your React or Angular applications are applications which are either active or dormant. When active, they listen to url routing events and put content on the DOM. When dormant, they do not listen to url routing events and are totally removed from the DOM.
2. A single-spa-config. The single-spa-config is the html page, plus the javascript that registers applications with single-spa. Each application is registered with three things:
   1. A name
   2. A function to load the application's code
   3. A function that determines when the application is active/dormant.

How hard will it be to use single-spa?

single-spa works with es5, es6+, typescript, webpack, systemjs, gulp, grunt, bower, ember-cli, or really anything build system you can think of. You can npm install it, jspm install it, or even just use a <script> tag if you prefer. If you're not starting your application from scratch, you'll have to migrate your SPA to become a single-spa application.

single-spa works in Chrome, Firefox, Safari, IE11, and Edge.

Isn't single-spa sort of a redundant name?

Yep

Documentation

See the docs. If you're looking for help with specific frameworks or build systems (React, Angular, Webpack, Ember, etc), check out the ecosystem wiki

Also, check out this step by step guide.

Simple Usage

For a full example, check out this simple webpack example.

To create a single-spa application, you will need to do three things:

1. Create an html file:

<html>
<body>
	<script src="single-spa-config.js"></script>
</body>
</html>

1. Create a single-spa-config. Check out the docs for more detail.

// single-spa-config.js
import * as singleSpa from 'single-spa';

const appName = 'app1';

/* The loading function is a function that returns a promise that resolves with the javascript application module.
 * The purpose of it is to facilitate lazy loading -- single-spa will not download the code for a application until it needs to.
 * In this example, import() is supported in webpack and returns a Promise, but single-spa works with any loading function that returns a Promise.
 */
const loadingFunction = () => import('./app1/app1.js');

/* Single-spa does some top-level routing to determine which application is active for any url. You can implement this routing any way you'd like.
 * One useful convention might be to prefix the url with the name of the app that is active, to keep your top-level routing simple.
 */
const activityFunction = location => location.pathname.startsWith('/app1');

singleSpa.registerApplication(appName, loadingFunction, activityFunction);
singleSpa.start();

1. Create an application. Check out the docs for more detail.

//app1.js

let domEl;

export function bootstrap(props) {
	return Promise
		.resolve()
		.then(() => {
			domEl = document.createElement('div');
			domEl.id = 'app1';
			document.body.appendChild(domEl);
		});
}

export function mount(props) {
	return Promise
		.resolve()
		.then(() => {
			// This is where you would normally use a framework to mount some ui to the dom. See https://github.com/CanopyTax/single-spa/blob/master/docs/single-spa-ecosystem.md.
			domEl.textContent = 'App 1 is mounted!'
		});
}

export function unmount(props) {
	return Promise
		.resolve()
		.then(() => {
			// This is normally where you would tell the framework to unmount the ui from the dom. See https://github.com/CanopyTax/single-spa/blob/master/docs/single-spa-ecosystem.md
			domEl.textContent = '';
		})
}

Project roadmap

We're trying out github's Projects feature (here) and are keeping it up-to-date with the fancy things in the works for single-spa.

API

See single-spa api and application api.

Who's Using This?

Please submit a P.R. to this section if you start using single-spa.

• CanopyTax
• Dealer Socket
• Beamery