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

Multiple applications all lazily loaded and mounted/unmounted in the same single page application (SPA). The apps can be deployed independently to your web server of choice, lazy-loaded onto the page independently, and nested.

In this context, an application is an html document that pulls in JS, CSS, and more HTML. This means that many pre-existing applications do not need to change at all in order to work with single-spa.

View the demo!

A demo is live on surge.sh. Don't be turned off by the lack of styling -- I'll be fixing that soon. It's based on the code in the examples repository.

Ideology

The hope here is that "one SPA to rule them all" will help scale teams and organizations that have complex apps -- this is done by making it easier to split code and then deploy it independently. To explain why single SPA is advantageous, consider the following disadvantages of a multiple SPA approach:

1. Implementation details are usually reflected in the URL (different subdomains for different SPAs, or different apps own different prefixes in the window.location.pathname)
2. Each SPA tends to become a monolith, since it's easier to add to an existing SPA than it is to figure out how to deploy a new SPA.
3. Transitioning between the apps is a full page unload-then-load, which generally provides a worse user experience. It is possible to mitigate this one with server-side routing + rendering (popularly done with React), but single-spa offers an alternative approach.
4. Shared functionality can only be accomplished via shared libraries, instead of a service oriented architecture ("Update it and hope library consumers upgrade" vs "Deploy it once and now everyone has it")

How to use it

In general, the process is to create a root app which imports single-spa and declares child applications by calling singleSpa.declareChildApplication(...). Each child application starts out as just a single-spa.config.js file, with the rest of the app (the html document, the js, the css, etc) being lazy loaded later on. As the app is being loaded, mounted, unmounted, etc., lifecycle functions are called to allow customized behavior. SSPA plugins are written to standardize the lifecycle functions for popular technologies like angular, jspm, react, webpack, etc.

Configuring JSPM apps to be SSPA apps.

jspm install npm:single-spa-jspm and then add the following to your single-spa.config.js:

import { defaultJspmApp } from "single-spa-jspm";
export const lifecycles = [...(any other plugins)..., defaultJspmApp()]

Thus far it seems that it's best to put your JSPM lifecycles at the end of the array.

Read the examples

So right now it's still somewhat alpha and so the best thing to do is look at the examples repository. Especially the following files:

• The index.html file
• The root app
• The children apps

Also note that it requires that as of 10/19/15, the root app that loads all other apps must be written with JSPM. The goal is to move away from that towards the whatwg/loader standard or maybe towards no loader standard at all (which would offload all of the loading work to the user).

Things that are not supported

• Single Spa is the one who controls the <base> tag, which means that apps should not control it. single-spa-angular1 makes it possible for angular to still work (even with History API pretty urls!) without the angular app putting a <base> tag in the app's index.html.