0
# Single-SPA
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: single-spa
7
- **Package Type**: npm
8
- **Language**: JavaScript with TypeScript definitions
9
- **Installation**: `npm install single-spa`
10
11
## Core Imports
12
13
```javascript
14
import {
15
registerApplication,
16
start,
17
navigateToUrl,
18
getMountedApps
19
} from "single-spa";
20
```
21
22
For CommonJS:
23
24
```javascript
25
const {
26
registerApplication,
27
start,
28
navigateToUrl,
29
getMountedApps
30
} = require("single-spa");
31
```
32
33
## Basic Usage
34
35
```javascript
36
import { registerApplication, start } from "single-spa";
37
38
// Register a microfrontend application
39
registerApplication({
40
name: "navbar",
41
app: () => import("./navbar/navbar.app.js"),
42
activeWhen: "/",
43
customProps: { theme: "dark" }
44
});
45
46
// Register another application
47
registerApplication({
48
name: "products",
49
app: () => import("./products/products.app.js"),
50
activeWhen: "/products"
51
});
52
53
// Start single-spa
54
start();
55
```
56
57
## Architecture
58
59
Single-SPA is built around several key concepts:
60
61
- **Applications**: Microfrontend applications with lifecycle methods (bootstrap, mount, unmount)
62
- **Activity Functions**: Determine when applications should be active based on routing
63
- **Lifecycle Management**: Automatic mounting/unmounting of applications as user navigates
64
- **Parcels**: Manually managed components that can be mounted anywhere
65
- **Error Handling**: Global error handling system for application failures
66
- **Navigation**: History API integration for seamless routing
67
68
## Capabilities
69
70
### Application Management
71
72
Core functionality for registering, unregistering, and managing microfrontend applications throughout their lifecycle.
73
74
```javascript { .api }
75
function registerApplication(config: RegisterApplicationConfig): void;
76
function registerApplication(
77
appName: string,
78
applicationOrLoadingFn: Application,
79
activityFn: ActivityFn,
80
customProps?: CustomProps | CustomPropsFn
81
): void;
82
83
function unregisterApplication(appName: string): Promise<any>;
84
```
85
86
[Application Management](./application-management.md)
87
88
### Navigation & Routing
89
90
Navigation utilities and routing integration for managing URL changes and programmatic navigation between microfrontends.
91
92
```javascript { .api }
93
function navigateToUrl(obj: string | Event | HTMLAnchorElement, opts?: Object): void;
94
function triggerAppChange(): Promise<any>;
95
```
96
97
[Navigation & Routing](./navigation-routing.md)
98
99
### Application Status & Lifecycle
100
101
Status constants and utilities for monitoring application states and lifecycle management.
102
103
```javascript { .api }
104
function getAppStatus(appName: string): string | null;
105
function getMountedApps(): string[];
106
107
// Status constants
108
const NOT_LOADED = "NOT_LOADED";
109
const MOUNTED = "MOUNTED";
110
// ... other status constants
111
```
112
113
[Application Status & Lifecycle](./application-status-lifecycle.md)
114
115
### Parcels System
116
117
Manual component management system for mounting components outside of the standard application lifecycle.
118
119
```javascript { .api }
120
function mountRootParcel(
121
parcelConfig: ParcelConfig,
122
parcelProps: ParcelProps & CustomProps
123
): Parcel;
124
```
125
126
[Parcels System](./parcels-system.md)
127
128
### Error Handling
129
130
Global error handling system for managing application errors and failures.
131
132
```javascript { .api }
133
function addErrorHandler(handler: (error: AppError) => void): void;
134
function removeErrorHandler(handler: (error: AppError) => void): void;
135
```
136
137
[Error Handling](./error-handling.md)
138
139
### Configuration & Timeouts
140
141
Configuration utilities for setting application lifecycle timeouts and framework-specific options.
142
143
```javascript { .api }
144
function start(opts?: StartOpts): void;
145
function setMountMaxTime(time: number, dieOnTimeout?: boolean, warningMillis?: number): void;
146
```
147
148
[Configuration & Timeouts](./configuration-timeouts.md)
149
150
## Core Types
151
152
```javascript { .api }
153
interface RegisterApplicationConfig {
154
name: string;
155
app: Application;
156
activeWhen: Activity;
157
customProps?: CustomProps | CustomPropsFn;
158
}
159
160
interface LifeCycles {
161
bootstrap: LifeCycleFn | Array<LifeCycleFn>;
162
mount: LifeCycleFn | Array<LifeCycleFn>;
163
unmount: LifeCycleFn | Array<LifeCycleFn>;
164
update?: LifeCycleFn | Array<LifeCycleFn>;
165
}
166
167
interface AppProps {
168
name: string;
169
singleSpa: any;
170
mountParcel: (parcelConfig: ParcelConfig, customProps: ParcelProps & CustomProps) => Parcel;
171
}
172
173
type Application = LifeCycles | ((config: AppProps) => Promise<LifeCycles>);
174
type ActivityFn = (location: Location) => boolean;
175
type Activity = ActivityFn | string | Array<ActivityFn | string>;
176
type LifeCycleFn = (config: AppProps) => Promise<any>;
177
178
interface StartOpts {
179
urlRerouteOnly?: boolean;
180
}
181
```