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

Combine multiple SPAs into one SPA by implementing lifecycle functions. Allows you to:

• Trade off between frameworks without refreshing the page (React, ng1, ng2, ember, or whatever you're using)
• Lazy load code for improved initial load time. This is baked in and requires no configuration.
• Ensure that no single part of the app can break everything.

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

Architectural Overview

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

1. An index.html file
2. A root application, in which child applications are registered. In order to register a child application, two things must be provided:
3. The url to the application
4. A function that determines if the application is active
5. Many child applications, each of which is like an SPA itself. Child applications respond to url routing events and must know how to bootstrap, mount, and unmount themselves from the DOM.

Prerequistes

In order to use single-spa, you must be using a javascript loader. Since loaders are not yet supported natively by browsers, you'll have to use a polyfill, such as SystemJS. If you're using a bundler (such as webpack or browserify) instead of a loader, or if you're using a non-standard loader (such as requirejs), check out the migration guide to see your options.

Documentation

See the docs directory.

Simple Usage

Note: this example uses jspm, since it's the easiest way to set up a loader. However, jspm and systemjs are not required.

npm install -g jspm@beta
jspm init
jspm install npm:single-spa

Create an index.html file (see docs for more detail).

<html>
  <head>
    <script src="jspm_packages/system.src.js"></script>
    <script src="jspm.browser.js"></script>
    <script src="jspm.config.js"></script>
    <script>
      System.import('src/main.js');
    </script>
  </head>
  <body>
    <div id="main-content"></div>
  </body>
</html>

Create the root application (see docs for more detail).

// src/main.js
import { declareChildApplication } from "single-spa";
declareChildApplication('/apps/app1/app1.js', () => window.location.hash === '');

Create the child application (see docs for more detail).

document.getElementById('main-content').textContent += "App1 is loaded.";

// apps/app1/app1.js
export function bootstrap() {
  return new Promise((resolve, reject) => {
    document.getElementById('main-content').textContent += "App1 is bootstrapped.";
    resolve();
  });
}

export function mount() {
  return new Promise((resolve, reject) => {
    document.getElementById('main-content').textContent += "App1 is mounted!";
    resolve();
  });
}

export function unmount() {
  return new Promise((resolve, reject) => {
    document.getElementById('main-content').textContent = "";
    resolve();
  });
}

API

See single-spa api and child application api.

View the demo!

A demo is live on surge.sh, but is based on an old version of single-spa. The demo will soon be updated to use single-spa@2.x