Nested Applications

Nested Applications Overview

At its core, nested applications 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 nested applications pays off across the whole codebase: fewer surprises, easier testing, and smoother onboarding. The snippet below is a solid starting point.

import { registerApplication, start } from 'single-spa';

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

start();

single-spa orchestrates multiple framework apps on one page through a root config.

Nested Applications Example

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

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

Single-SPA Cheatsheet

Core single-spa APIs related to nested applications.

How Nested Applications Works in Single-SPA

Nested Applications 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.

single-spa orchestrates multiple framework apps on one page through a root config.

• 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 Nested Applications

For reliable micro frontends, nested applications 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

• Copying nested applications snippets without understanding what each line does.
• Skipping error handling and edge cases when wiring up nested applications.
• Leaving nested applications untested, so regressions slip into production.
• Over-engineering nested applications before you actually need the extra flexibility.

Key Takeaways

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