Layout Definition

Layout Definition Overview

At its core, layout definition is about doing one thing well inside your single-spa project. Once you understand the pattern, you can apply it consistently across features and teams.

Good layout definition pays off across the whole codebase: fewer surprises, easier testing, and smoother onboarding. The snippet below is a solid starting point.

<single-spa-router>
  <nav>
    <application name="@org/navbar"></application>
  </nav>
  <route path="checkout">
    <application name="@org/checkout"></application>
  </route>
</single-spa-router>

The single-spa layout engine declares where applications render for each route.

Layout Definition Example

registerApplication({
  name: '@org/app',
  app: () => System.import('@org/app'),
  activeWhen: ['/app'],
});
start();

• Start from a minimal Layout Definition example and grow it only as needed.
• Keep configuration explicit so Layout Definition behaves the same in every environment.
• Name things clearly so teammates understand your Layout Definition at a glance.
• Add tests around Layout Definition early to lock in expected behaviour.

Single-SPA Cheatsheet

Core single-spa APIs related to layout definition.

How Layout Definition Works in Single-SPA

Layout Definition is part of how single-spa lets multiple applications — even in different frameworks — coexist on one page. A root config registers each app and controls when it is active.

The single-spa layout engine declares where applications render for each route.

• A root config registers apps and calls start().
• Each app exports bootstrap, mount, and unmount lifecycles.
• activeWhen decides which routes each app owns.
• Import maps resolve each app's bundle at runtime.

Practical Guidance for Layout Definition

For reliable micro frontends, layout definition should isolate failures and keep shared state minimal. Let each team own its app end to end while agreeing on a few shared contracts.

Common Mistakes

• Skipping error handling and edge cases when wiring up layout definition.
• Leaving layout definition untested, so regressions slip into production.
• Over-engineering layout definition before you actually need the extra flexibility.
• Ignoring documentation, which makes layout definition hard for the next developer to change.

Key Takeaways

• Layout Definition is a core part of working effectively with single-spa.
• Start small and keep layout definition focused on a single responsibility.
• Apply consistent patterns so layout definition scales across your project.
• Test and document layout definition to keep it maintainable over time.