or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

application-management.mdapplication-status-lifecycle.mdconfiguration-timeouts.mderror-handling.mdindex.mdnavigation-routing.mdparcels-system.md
tile.json

tessl/npm-single-spa

The router for easy microfrontends that enables multiple frameworks to coexist on the same page.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/single-spa@6.0.x

To install, run

npx @tessl/cli install tessl/npm-single-spa@6.0.0

index.mddocs/

Single-SPA

Single-SPA is a JavaScript framework for building microfrontends that enables multiple frameworks (React, Angular, Vue, etc.) to coexist on the same page without page refreshes. It provides application lifecycle management, routing, and orchestration for microfrontend architectures.

Package Information

  • Package Name: single-spa
  • Package Type: npm
  • Language: JavaScript with TypeScript definitions
  • Installation: npm install single-spa

Core Imports

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

For CommonJS:

const { 
  registerApplication, 
  start, 
  navigateToUrl, 
  getMountedApps 
} = require("single-spa");

Basic Usage

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

// Register a microfrontend application
registerApplication({
  name: "navbar",
  app: () => import("./navbar/navbar.app.js"),
  activeWhen: "/",
  customProps: { theme: "dark" }
});

// Register another application
registerApplication({
  name: "products", 
  app: () => import("./products/products.app.js"),
  activeWhen: "/products"
});

// Start single-spa
start();

Architecture

Single-SPA is built around several key concepts:

  • Applications: Microfrontend applications with lifecycle methods (bootstrap, mount, unmount)
  • Activity Functions: Determine when applications should be active based on routing
  • Lifecycle Management: Automatic mounting/unmounting of applications as user navigates
  • Parcels: Manually managed components that can be mounted anywhere
  • Error Handling: Global error handling system for application failures
  • Navigation: History API integration for seamless routing

Capabilities

Application Management

Core functionality for registering, unregistering, and managing microfrontend applications throughout their lifecycle.

function registerApplication(config: RegisterApplicationConfig): void;
function registerApplication(
  appName: string,
  applicationOrLoadingFn: Application,
  activityFn: ActivityFn,
  customProps?: CustomProps | CustomPropsFn
): void;

function unregisterApplication(appName: string): Promise<any>;

Application Management

Navigation & Routing

Navigation utilities and routing integration for managing URL changes and programmatic navigation between microfrontends.

function navigateToUrl(obj: string | Event | HTMLAnchorElement, opts?: Object): void;
function triggerAppChange(): Promise<any>;

Navigation & Routing

Application Status & Lifecycle

Status constants and utilities for monitoring application states and lifecycle management.

function getAppStatus(appName: string): string | null;
function getMountedApps(): string[];

// Status constants
const NOT_LOADED = "NOT_LOADED";
const MOUNTED = "MOUNTED";
// ... other status constants

Application Status & Lifecycle

Parcels System

Manual component management system for mounting components outside of the standard application lifecycle.

function mountRootParcel(
  parcelConfig: ParcelConfig,
  parcelProps: ParcelProps & CustomProps
): Parcel;

Parcels System

Error Handling

Global error handling system for managing application errors and failures.

function addErrorHandler(handler: (error: AppError) => void): void;
function removeErrorHandler(handler: (error: AppError) => void): void;

Error Handling

Configuration & Timeouts

Configuration utilities for setting application lifecycle timeouts and framework-specific options.

function start(opts?: StartOpts): void;
function setMountMaxTime(time: number, dieOnTimeout?: boolean, warningMillis?: number): void;

Configuration & Timeouts

Core Types

interface RegisterApplicationConfig {
  name: string;
  app: Application;
  activeWhen: Activity;
  customProps?: CustomProps | CustomPropsFn;
}

interface LifeCycles {
  bootstrap: LifeCycleFn | Array<LifeCycleFn>;
  mount: LifeCycleFn | Array<LifeCycleFn>;
  unmount: LifeCycleFn | Array<LifeCycleFn>;
  update?: LifeCycleFn | Array<LifeCycleFn>;
}

interface AppProps {
  name: string;
  singleSpa: any;
  mountParcel: (parcelConfig: ParcelConfig, customProps: ParcelProps & CustomProps) => Parcel;
}

type Application = LifeCycles | ((config: AppProps) => Promise<LifeCycles>);
type ActivityFn = (location: Location) => boolean;
type Activity = ActivityFn | string | Array<ActivityFn | string>;
type LifeCycleFn = (config: AppProps) => Promise<any>;

interface StartOpts {
  urlRerouteOnly?: boolean;
}