# 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

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: 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.

Takeaway: 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: 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.

Takeaway: 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`

```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();
```

## Ratings

_Editorial judgement for a typical team, from 1 to 5._

- **Team independence: 4/5** (higher is better). Each application is loaded by the root config from its own build, so it can deploy separately.
- **Runtime performance: 2/5** (higher is better). Several frameworks and their lifecycles on one page can add up to a lot of JavaScript.
- **Complexity: 4/5** (lower is simpler). You own the root config, each application's lifecycle functions, routing and shared libraries.
- **SSR / SEO support: 2/5** (higher is better). Server rendering relies on the optional layout engine and needs extra setup.
- **Tech-agnostic: 5/5** (higher is better). Designed to run applications in different frameworks on one page.
- **Isolation: 2/5** (higher is better). Applications share one page, so styles and globals can collide unless teams scope them.
- **UX consistency: 3/5** (higher is better). Different frameworks make a shared design system harder to apply everywhere.
- **Tooling maturity: 3/5** (higher is better). Established documentation, project generator and framework helpers, but no stable release since September 2024.

## 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](https://github.com/single-spa/single-spa/releases)).

## Sources

- [Getting Started with single-spa](https://single-spa.js.org/docs/getting-started-overview/), single-spa.js.org
- [Configuring single-spa](https://single-spa.js.org/docs/configuration/), single-spa.js.org
- [single-spa releases](https://github.com/single-spa/single-spa/releases), GitHub, single-spa/single-spa

https://microfrontends.dev/approaches/single-spa