Runtime

single-spa

A small root config registers each application with the routes it owns, then mounts and unmounts it, even when the applications use different frameworks.

How it works

@shop/search (React)Team A
@shop/cart (Angular)Team B
shared librariesShared
root config · in the browserShell
Dashed lines: loaded at runtime · by route
  1. Root config. A root config registers each application with a name, a function that loads it, and when it is active.
  2. Route matches. On /search, single-spa loads team A's application and calls its bootstrap and mount functions.
  3. Route changes. On /cart, team A's application unmounts and team B's mounts, in another framework, without a full page reload.
  4. Shared libraries. Common libraries can be shared so they load once instead of once per application.

Try it

Demo I

Routing ownership

A shell at shop.example.com hosts Team A's Search and Team B's Cart. When the shell owns every route, its route table lists /search, /cart and /cart/:id. /cart/42 renders Team B's item page, but /cart/42/gift, a page Team B shipped today, gets the shell's not-found page until the shell adds the route and redeploys, and /cart/oops gets the same not-found page. When the shell owns only the prefix, it sends /search/* to Team A and /cart/* to Team B, whose own router matches the rest. /cart/42 and /cart/42/gift both render without touching the shell, but /cart/oops now reaches Team B, which shows its own not-found page, and the shell can't tell the path was invalid. The model leaves out server status codes and the back button.

Decide who owns each part of the URL.In our view, the shell should own the first path segment and each app what follows, with one not-found page everyone agrees on. single-spa's activeWhen works this way: the root config picks the application by URL, and that application's router does the rest.
Demo F

Communication patterns

Team A's product page and Team B's cart need to talk when a product is added. With a custom event, Team A dispatches cart:add on window and Team B listens: the teams share only the event name and its payload, so coupling is low. With the URL, Team A writes ?cart=1 and then announces the change with a popstate event, because writing the URL fires none, and Team B re-reads the URL when it hears it: also low, and it survives reloads and sharing, but it suits only small, serializable state. With props from the shell, Team A calls a callback the shell gave it and the shell re-renders Team B: medium, because the shell has to know both apps' APIs. With a shared store, both apps dispatch to and subscribe to one store: high, because both depend on one library, one version and one state shape.

Use the loosest pattern that works.In our view, events and the URL keep teams independent, props from the shell tie both to the shell, and a shared store ties them to each other.

Pros

  • Different frameworks can run side by side on one page.
  • A clear lifecycle for every application: bootstrap, mount, unmount.
  • Suits migrating a legacy app one route at a time.

Cons

  • Several frameworks on one page means more to download.
  • The root config, lifecycles and routing glue are code your team owns.
  • Server rendering needs its optional layout engine and extra setup.

Best when

  • Migrating from a legacy framework piece by piece.
  • Teams that must keep different stacks.
  • Ownership that follows routes.

Avoid when

  • Everyone already uses one framework.
  • SEO-critical pages that need server rendering.
  • Small organizations with nobody to own the root config.

In code

root-config.js
import { registerApplication, start } from "single-spa";

registerApplication({
  name: "@shop/search",
  app: () => import("@shop/search"), // resolved at runtime by the import map, not bundled
  activeWhen: ["/search"],
});

start();

Tooling and ecosystem

single-spa is framework-agnostic: its documentation names React, Angular, AngularJS and Ember among the frameworks it can combine, and says it works with ES5, ES6+, TypeScript, webpack, SystemJS and other build tools. The root config must call start() before any application mounts. SystemJS is one of the tools it works with, not a requirement. For server rendering, the optional single-spa Layout Engine is recommended.

Releases have slowed. The latest stable version is 6.0.3, from 29 September 2024, and 7.0 has stayed in beta since 7.0.0-beta.13, from 22 September 2025 (GitHub releases).