Skip to main content
Version: 5.x

Layout Engine


Github repository

The single-spa-layout npm package is an optional add-on to single-spa. The layout engine provides a routing API that controls your top level routes, applications, and dom elements. Using single-spa-layout makes it easier to accomplish the following:

  • DOM placement and ordering of applications.
  • Loading UIs when applications are downloaded.
  • Default routes for Not Found / 404 pages.
  • Transitions between routes (implementation pending).
  • Server side rendering of single-spa applications
  • Error pages

In the browser, the layout engine performs two major tasks:

  1. Generate single-spa registration config from an HTML Element and/or JSON object.
  2. Listen to routing events to ensure that all DOM elements are laid out correctly before the single-spa applications are mounted.

On the server, the layout engine performs two tasks:

  1. Construct a server layout object from an HTML template.
  2. Send an HTML document (HTTP response headers and body) to the browser, based on the server layout object and current route.

single-spa-layout is 3.2kb gzipped (9kb ungzipped).


You only need to install the layout engine into your root config (not in any other application).

npm install --save single-spa-layout

# or
yarn add single-spa-layout

Browser / NodeJS support

single-spa-layout works in all browsers supported by single-spa, including IE11. On the server, all NodeJS versions that support ESM are supported.


You must use single-spa@>=5.4.0 in order for the layout engine to work. Additionally, you may not provide custom domElementGetter functions for any of your single-spa applications, as those override the configuration within single-spa-layout.

Basic usage

In your root html file, add a <template> element to the head. It should have a <single-spa-router> element that contains <route> elements, <application> elements, and any other dom elements:

<template id="single-spa-layout">
<nav class="topnav">
<application name="@organization/nav"></application>
<div class="main-content">
<route path="settings">
<application name="@organization/settings"></application>
<route path="clients">
<application name="@organization/clients"></application>
<application name="@organization/footer"></application>

Then inside of your root-config's JavaScript code, add the following:

import { registerApplication, start } from "single-spa";
import {
} from "single-spa-layout";

const routes = constructRoutes(document.querySelector("#single-spa-layout"));
const applications = constructApplications({
loadApp({ name }) {
return System.import(name);
const layoutEngine = constructLayoutEngine({ routes, applications });