Layout Engine

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:

Generate single-spa registration config from an HTML Element and/or JSON object.
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:

Construct a server layout object from an HTML template.
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

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.

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:

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

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

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

Edit this page

Overview

Layout Engine