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
```