0
# Configuration & Timeouts
1

2
Configuration utilities for setting application lifecycle timeouts, framework startup options, and integration settings.
3

4
## Capabilities
5

6
### Start Single-SPA
7

8
Initializes single-spa and begins managing applications. This function must be called to activate the microfrontend system.
9

10
```javascript { .api }
11
/**
12
 * Start single-spa and begin managing applications
13
 * @param opts - Optional configuration options
14
 */
15
function start(opts?: StartOpts): void;
16

17
interface StartOpts {
18
  urlRerouteOnly?: boolean;
19
}
20
```
21

22
**Usage Examples:**
23

24
```javascript
25
import { start } from "single-spa";
26

27
// Basic start
28
start();
29

30
// Start with URL-only rerouting (performance optimization)
31
start({ urlRerouteOnly: true });
32

33
// Typical application initialization
34
import { registerApplication, start } from "single-spa";
35

36
// Register all applications first
37
registerApplication({
38
  name: "navbar",
39
  app: () => import("./navbar/navbar.app.js"),
40
  activeWhen: "/"
41
});
42

43
registerApplication({
44
  name: "main-content",
45
  app: () => import("./main/main.app.js"),
46
  activeWhen: "/app"
47
});
48

49
// Then start single-spa
50
start();
51

52
// Conditional start based on environment
53
if (window.singleSpaReady) {
54
  start();
55
} else {
56
  window.addEventListener("single-spa-ready", () => start());
57
}
58
```
59

60
### Bootstrap Timeout Configuration
61

62
Sets the maximum time allowed for application bootstrapping. Applications that exceed this timeout will be marked as broken.
63

64
```javascript { .api }
65
/**
66
 * Set maximum time for application bootstrap lifecycle
67
 * @param time - Timeout in milliseconds
68
 * @param dieOnTimeout - Whether to throw error on timeout (default: false)
69
 * @param warningMillis - Warning threshold in milliseconds (default: 1000)
70
 */
71
function setBootstrapMaxTime(
72
  time: number,
73
  dieOnTimeout?: boolean,
74
  warningMillis?: number
75
): void;
76
```
77

78
**Usage Examples:**
79

80
```javascript
81
import { setBootstrapMaxTime } from "single-spa";
82

83
// Set 10 second bootstrap timeout
84
setBootstrapMaxTime(10000);
85

86
// Set timeout with error throwing enabled
87
setBootstrapMaxTime(5000, true);
88

89
// Set timeout with custom warning threshold
90
setBootstrapMaxTime(8000, false, 3000); // Warn after 3s, timeout after 8s
91

92
// Environment-based configuration
93
const isProduction = process.env.NODE_ENV === "production";
94
setBootstrapMaxTime(
95
  isProduction ? 5000 : 30000, // Shorter timeout in production
96
  isProduction, // Die on timeout in production
97
  isProduction ? 2000 : 5000 // Earlier warning in production
98
);
99
```
100

101
### Mount Timeout Configuration
102

103
Sets the maximum time allowed for application mounting.
104

105
```javascript { .api }
106
/**
107
 * Set maximum time for application mount lifecycle
108
 * @param time - Timeout in milliseconds
109
 * @param dieOnTimeout - Whether to throw error on timeout (default: false)
110
 * @param warningMillis - Warning threshold in milliseconds (default: 1000)
111
 */
112
function setMountMaxTime(
113
  time: number,
114
  dieOnTimeout?: boolean,
115
  warningMillis?: number
116
): void;
117
```
118

119
**Usage Examples:**
120

121
```javascript
122
import { setMountMaxTime } from "single-spa";
123

124
// Standard mount timeout
125
setMountMaxTime(5000);
126

127
// Quick mount timeout for simple applications
128
setMountMaxTime(2000, true, 1000);
129

130
// Longer timeout for heavy applications
131
setMountMaxTime(15000, false, 5000);
132

133
// Dynamic timeout based on application complexity
134
function configureTimeouts() {
135
  const heavyApps = ["dashboard", "data-visualization"];
136
  const currentApp = getCurrentAppName();
137
  
138
  if (heavyApps.includes(currentApp)) {
139
    setMountMaxTime(10000, false, 3000);
140
  } else {
141
    setMountMaxTime(3000, true, 1000);
142
  }
143
}
144
```
145

146
### Unmount Timeout Configuration
147

148
Sets the maximum time allowed for application unmounting.
149

150
```javascript { .api }
151
/**
152
 * Set maximum time for application unmount lifecycle
153
 * @param time - Timeout in milliseconds
154
 * @param dieOnTimeout - Whether to throw error on timeout (default: false)
155
 * @param warningMillis - Warning threshold in milliseconds (default: 1000)
156
 */
157
function setUnmountMaxTime(
158
  time: number,
159
  dieOnTimeout?: boolean,
160
  warningMillis?: number
161
): void;
162
```
163

164
**Usage Examples:**
165

166
```javascript
167
import { setUnmountMaxTime } from "single-spa";
168

169
// Quick unmount timeout
170
setUnmountMaxTime(3000);
171

172
// Strict unmount timeout
173
setUnmountMaxTime(2000, true);
174

175
// Graceful unmount with longer timeout
176
setUnmountMaxTime(8000, false, 2000);
177
```
178

179
### Unload Timeout Configuration
180

181
Sets the maximum time allowed for application unloading.
182

183
```javascript { .api }
184
/**
185
 * Set maximum time for application unload lifecycle
186
 * @param time - Timeout in milliseconds
187
 * @param dieOnTimeout - Whether to throw error on timeout (default: false)
188
 * @param warningMillis - Warning threshold in milliseconds (default: 1000)
189
 */
190
function setUnloadMaxTime(
191
  time: number,
192
  dieOnTimeout?: boolean,
193
  warningMillis?: number
194
): void;
195
```
196

197
**Usage Examples:**
198

199
```javascript
200
import { setUnloadMaxTime } from "single-spa";
201

202
// Standard unload timeout
203
setUnloadMaxTime(5000);
204

205
// Force unload quickly
206
setUnloadMaxTime(3000, true);
207
```
208

209
### jQuery Support
210

211
Ensures jQuery plays nicely with single-spa's routing system by preventing jQuery from interfering with navigation.
212

213
```javascript { .api }
214
/**
215
 * Ensure jQuery doesn't interfere with single-spa routing
216
 * @param jQuery - Optional jQuery instance (auto-detected if not provided)
217
 */
218
function ensureJQuerySupport(jQuery?: any): void;
219
```
220

221
**Usage Examples:**
222

223
```javascript
224
import { ensureJQuerySupport } from "single-spa";
225

226
// Auto-detect jQuery
227
ensureJQuerySupport();
228

229
// Provide specific jQuery instance
230
import $ from "jquery";
231
ensureJQuerySupport($);
232

233
// Conditional jQuery support
234
if (window.jQuery) {
235
  ensureJQuerySupport(window.jQuery);
236
}
237
```
238

239
## Configuration Patterns
240

241
### Environment-Based Configuration
242

243
```javascript
244
import { 
245
  start, 
246
  setBootstrapMaxTime, 
247
  setMountMaxTime, 
248
  setUnmountMaxTime,
249
  addErrorHandler 
250
} from "single-spa";
251

252
class SingleSpaConfig {
253
  static configure() {
254
    const env = process.env.NODE_ENV;
255
    const isDev = env === "development";
256
    const isProd = env === "production";
257
    
258
    // Configure timeouts based on environment
259
    if (isDev) {
260
      // Generous timeouts for development
261
      setBootstrapMaxTime(30000, false, 10000);
262
      setMountMaxTime(15000, false, 5000);
263
      setUnmountMaxTime(10000, false, 3000);
264
    } else if (isProd) {
265
      // Strict timeouts for production
266
      setBootstrapMaxTime(5000, true, 2000);
267
      setMountMaxTime(3000, true, 1000);
268
      setUnmountMaxTime(2000, true, 500);
269
    }
270
    
271
    // Configure error handling
272
    if (isDev) {
273
      addErrorHandler((error) => {
274
        console.error("Development error:", error);
275
      });
276
    }
277
    
278
    // Start with appropriate options
279
    start({ 
280
      urlRerouteOnly: isProd // Performance optimization for production
281
    });
282
  }
283
}
284

285
// Initialize configuration
286
SingleSpaConfig.configure();
287
```
288

289
### Progressive Configuration
290

291
```javascript
292
import { 
293
  start, 
294
  setBootstrapMaxTime, 
295
  setMountMaxTime,
296
  registerApplication 
297
} from "single-spa";
298

299
// Configure timeouts progressively as applications are registered
300
const appConfigs = [
301
  {
302
    name: "shell",
303
    timeouts: { bootstrap: 3000, mount: 2000, unmount: 1000 }
304
  },
305
  {
306
    name: "heavy-dashboard",
307
    timeouts: { bootstrap: 10000, mount: 8000, unmount: 5000 }
308
  },
309
  {
310
    name: "simple-widget",
311
    timeouts: { bootstrap: 2000, mount: 1000, unmount: 500 }
312
  }
313
];
314

315
async function configureAndRegisterApps() {
316
  for (const config of appConfigs) {
317
    // Set timeouts for this specific app registration
318
    setBootstrapMaxTime(config.timeouts.bootstrap);
319
    setMountMaxTime(config.timeouts.mount);
320
    setUnmountMaxTime(config.timeouts.unmount);
321
    
322
    // Register the application
323
    registerApplication({
324
      name: config.name,
325
      app: () => import(`./apps/${config.name}/${config.name}.app.js`),
326
      activeWhen: `/${config.name}`
327
    });
328
  }
329
  
330
  // Start single-spa after all apps are registered
331
  start();
332
}
333
```
334

335
### Performance Monitoring Configuration
336

337
```javascript
338
import { 
339
  start, 
340
  setBootstrapMaxTime, 
341
  setMountMaxTime, 
342
  setUnmountMaxTime,
343
  addErrorHandler 
344
} from "single-spa";
345

346
class PerformanceMonitor {
347
  constructor() {
348
    this.metrics = new Map();
349
    this.setupTimeouts();
350
    this.setupErrorHandling();
351
  }
352
  
353
  setupTimeouts() {
354
    // Set timeouts with performance tracking
355
    const bootstrapTimeout = 5000;
356
    const mountTimeout = 3000;
357
    const unmountTimeout = 2000;
358
    
359
    setBootstrapMaxTime(bootstrapTimeout, false, bootstrapTimeout * 0.5);
360
    setMountMaxTime(mountTimeout, false, mountTimeout * 0.5);
361
    setUnmountMaxTime(unmountTimeout, false, unmountTimeout * 0.5);
362
  }
363
  
364
  setupErrorHandling() {
365
    addErrorHandler((error) => {
366
      if (error.message.includes("timeout")) {
367
        this.recordTimeout(error.appOrParcelName, error.message);
368
      }
369
    });
370
  }
371
  
372
  recordTimeout(appName, message) {
373
    const metric = this.metrics.get(appName) || { timeouts: 0, lastTimeout: null };
374
    metric.timeouts++;
375
    metric.lastTimeout = new Date();
376
    this.metrics.set(appName, metric);
377
    
378
    console.warn(`Performance issue: ${appName} timed out (${metric.timeouts} times)`);
379
    
380
    // Adjust timeouts dynamically
381
    if (metric.timeouts > 3) {
382
      console.log(`Increasing timeouts for ${appName} due to repeated issues`);
383
      this.increaseTimeouts(appName);
384
    }
385
  }
386
  
387
  increaseTimeouts(appName) {
388
    // Increase timeouts for problematic applications
389
    setBootstrapMaxTime(10000);
390
    setMountMaxTime(8000);
391
    setUnmountMaxTime(5000);
392
  }
393
  
394
  getPerformanceReport() {
395
    const report = {};
396
    this.metrics.forEach((metric, appName) => {
397
      report[appName] = {
398
        timeoutCount: metric.timeouts,
399
        lastTimeout: metric.lastTimeout,
400
        needsAttention: metric.timeouts > 2
401
      };
402
    });
403
    return report;
404
  }
405
}
406

407
// Initialize performance monitoring
408
const performanceMonitor = new PerformanceMonitor();
409

410
// Start single-spa
411
start();
412
```
413

414
### Feature Flag Configuration
415

416
```javascript
417
import { start, ensureJQuerySupport } from "single-spa";
418

419
class FeatureFlagConfig {
420
  static async configure() {
421
    // Load feature flags
422
    const flags = await this.loadFeatureFlags();
423
    
424
    // Configure based on flags
425
    if (flags.jquerySupport) {
426
      ensureJQuerySupport();
427
    }
428
    
429
    if (flags.urlRerouteOnly) {
430
      start({ urlRerouteOnly: true });
431
    } else {
432
      start();
433
    }
434
    
435
    if (flags.strictTimeouts) {
436
      this.configureStrictTimeouts();
437
    } else {
438
      this.configureRelaxedTimeouts();
439
    }
440
  }
441
  
442
  static async loadFeatureFlags() {
443
    try {
444
      const response = await fetch("/api/feature-flags");
445
      return await response.json();
446
    } catch (error) {
447
      console.warn("Failed to load feature flags, using defaults");
448
      return {
449
        jquerySupport: false,
450
        urlRerouteOnly: false,
451
        strictTimeouts: false
452
      };
453
    }
454
  }
455
  
456
  static configureStrictTimeouts() {
457
    setBootstrapMaxTime(3000, true, 1000);
458
    setMountMaxTime(2000, true, 500);
459
    setUnmountMaxTime(1000, true, 300);
460
  }
461
  
462
  static configureRelaxedTimeouts() {
463
    setBootstrapMaxTime(10000, false, 5000);
464
    setMountMaxTime(8000, false, 3000);
465
    setUnmountMaxTime(5000, false, 2000);
466
  }
467
}
468

469
// Initialize with feature flags
470
FeatureFlagConfig.configure();
471
```
472

473
## Best Practices
474

475
### Timeout Configuration Guidelines
476

477
```javascript
478
// Recommended timeout configurations by application type
479

480
// Lightweight applications (simple widgets, headers, footers)
481
setBootstrapMaxTime(2000, true, 1000);
482
setMountMaxTime(1000, true, 500);
483
setUnmountMaxTime(500, true, 200);
484

485
// Standard applications (forms, content pages)
486
setBootstrapMaxTime(5000, false, 2000);
487
setMountMaxTime(3000, false, 1000);
488
setUnmountMaxTime(2000, false, 500);
489

490
// Heavy applications (dashboards, data visualization, complex SPAs)
491
setBootstrapMaxTime(10000, false, 5000);
492
setMountMaxTime(8000, false, 3000);
493
setUnmountMaxTime(5000, false, 2000);
494

495
// Legacy applications (older frameworks, complex dependencies)
496
setBootstrapMaxTime(15000, false, 8000);
497
setMountMaxTime(12000, false, 5000);
498
setUnmountMaxTime(8000, false, 3000);
499
```