single-spa — The Router for Easy Microfrontends

Introduction

single-spa is a JavaScript micro-frontend framework that acts as a top-level router for independently deployed front-end applications. It manages the lifecycle of multiple apps on a single page, mounting and unmounting them based on URL routes. Teams can use different frameworks (React, Vue, Angular, Svelte) for different parts of the same application without conflict.

What single-spa Does

• Registers multiple applications with their own lifecycle hooks (bootstrap, mount, unmount)
• Routes between applications based on URL patterns using an activity function
• Loads applications lazily via dynamic import or SystemJS for code splitting
• Provides parcels for embedding one app inside another without routing
• Supports shared dependencies through import maps to avoid duplicate framework bundles

Architecture Overview

single-spa maintains a registry of applications, each defined by a name, a loading function, and an activity function that determines when the app is active. When the URL changes, single-spa evaluates all activity functions, unmounts inactive apps, and mounts active ones. Each app must export lifecycle functions. The framework is agnostic to how apps are built or bundled; it only manages their mounting lifecycle.

Self-Hosting & Configuration

• Use create-single-spa CLI to scaffold a root config and micro-apps with recommended defaults
• Configure import maps in the root HTML to map module names to deployed URLs
• Each micro-app is built as a SystemJS or ES module that exports lifecycle functions
• Use single-spa-layout for declarative HTML-based route configuration
• Deploy each micro-app independently to its own URL; the root config loads them at runtime

Key Features

• Framework-agnostic: official helpers exist for React, Vue, Angular, Svelte, and Web Components
• Applications load lazily and can be deployed independently without rebuilding the shell
• Import map overrides allow developers to test local changes against production micro-apps
• Browser dev tools extension for inspecting registered apps and their mount status
• Mature ecosystem with utilities for layout engine, module federation integration, and CSS isolation

Comparison with Similar Tools

• Qiankun — built on single-spa with added sandboxing and HTML entry; single-spa is the lower-level foundation
• Module Federation — build-time module sharing; single-spa is runtime-based and framework-agnostic
• Piral — React-focused micro-frontend shell; single-spa supports any framework
• iframe-based approaches — strong isolation but poor UX and communication; single-spa runs apps in-page
• Turbopack/Vite federation — bundler plugins for sharing modules; single-spa manages application lifecycles

FAQ

Q: Do all micro-apps need to use the same framework? A: No. Each app can use a different framework. single-spa only requires exported lifecycle functions.

Q: How do micro-apps share state? A: Through custom events, a shared observable store, or URL query parameters. single-spa does not prescribe a communication mechanism.

Q: Can I incrementally adopt single-spa? A: Yes. You can register your existing app as the only single-spa application and gradually extract new micro-apps over time.

Q: What about CSS conflicts between micro-apps? A: Use CSS Modules, shadow DOM, or naming conventions to scope styles. single-spa does not provide built-in CSS isolation.

Sources

• https://github.com/single-spa/single-spa
• https://single-spa.js.org