Version: 5.x

Applications API

Single-spa exports named functions and variables rather than a single default export. This means importing must happen in one of two ways:

  1. import { registerApplication, start } from 'single-spa';
  2. // or
  3. import * as singleSpa from 'single-spa';

registerApplication is the most important API your root config will use. Use this function to register any application within single-spa. Note that if an application is registered from within another application, that no hierarchy will be maintained between the applications.

There are two ways of registering your application:

  1. singleSpa.registerApplication(
  2. 'appName',
  3. () => System.import('appName'),
  4. location => location.pathname.startsWith('appName'),
  5. );

arguments

appName: string

App name that single-spa will register and reference this application with, and will be labelled with in dev tools.

applicationOrLoadingFn: () => <Function | Promise>

Must be a loading function that either returns the resolved application or a promise.

activityFn: (location) => boolean

Must be a pure function. The function is called with window.location as the first argument and should return a truthy value whenever the application should be active.

customProps?: Object | () => Object

Will be passed to the application during each lifecycle method.

returns

undefined

  1. singleSpa.registerApplication({
  2. name: 'appName',
  3. app: () => System.import('appName'),
  4. activeWhen: '/appName',
  5. customProps: {
  6. authToken: 'xc67f6as87f7s9d'
  7. }
  8. })
  9. singleSpa.registerApplication({
  10. name: 'appName',
  11. app: () => System.import('appName'),
  12. activeWhen: '/appName',
  13. // Dynamic custom props that can change based on route
  14. customProps(appName, location) {
  15. return {
  16. authToken: 'xc67f6as87f7s9d'
  17. }
  18. }
  19. })

arguments

name: string

App name that single-spa will register and reference this application with, and will be labelled with in dev tools.

app: Application | () => Application | Promise<Application>

Application object or a function that returns the resolved application (Promise or not)

activeWhen: string | (location) => boolean | (string | (location) => boolean)[]

Can be a path prefix which will match every URL starting with this path, an activity function (as described in the simple arguments) or an array containing both of them. If any of the criteria is true, it will keep the application active. The path prefix also accepts dynamic values (they must start with ‘:’), as some paths would receive url params and should still trigger your application. Examples:

  1. '/app1'
  2. https://app.com/app1
  3. https://app.com/app1/anything/everything
  4. 🚫 https://app.com/app2
  5. '/users/:userId/profile'
  6. https://app.com/users/123/profile
  7. https://app.com/users/123/profile/sub-profile/
  8. 🚫 https://app.com/users//profile/sub-profile/
  9. 🚫 https://app.com/users/profile/sub-profile/
  10. '/pathname/#/hash'
  11. https://app.com/pathname/#/hash
  12. https://app.com/pathname/#/hash/route/nested
  13. 🚫 https://app.com/pathname#/hash/route/nested
  14. 🚫 https://app.com/pathname#/another-hash
  15. ['/pathname/#/hash', '/app1']
  16. https://app.com/pathname/#/hash/route/nested
  17. https://app.com/app1/anything/everything
  18. 🚫 https://app.com/pathname/app1
  19. 🚫 https://app.com/app2

customProps?: Object | () => Object

Will be passed to the application during each lifecycle method.

returns

undefined

Applications API - 图1note

It is described in detail inside of the Configuration docs

  1. singleSpa.start();
  2. // Optionally, you can provide configuration
  3. singleSpa.start({
  4. urlRerouteOnly: true,
  5. });

Must be called by your single spa config. Before start is called, applications will be loaded, but will never be bootstrapped, mounted or unmounted. The reason for start is to give you control over the performance of your single page application. For example, you may want to declare registered applications immediately (to start downloading the code for the active ones), but not actually mount the registered applications until an initial AJAX request (maybe to get information about the logged in user) has been completed. In that case, the best performance is achieved by calling registerApplication immediately, but calling start after the AJAX request is completed.

arguments

The start(opts) api optionally accepts a single opts object, with the following properties. If the opts object is omitted, all defaults will be applied.

  • urlRerouteOnly: A boolean that defaults to false. If set to true, calls to history.pushState() and history.replaceState() will not trigger a single-spa reroute unless the client side route was changed. Setting this to true can be better for performance in some situations. For more information, read original issue.

returns

undefined

  1. singleSpa.triggerAppChange();

Returns a Promise that will resolve/reject when all apps have mounted/unmounted. This was built for testing single-spa and is likely not needed in a production application.

arguments

none

returns

Promise

Returns a Promise that will resolve/reject when all apps have mounted.

  1. // Three ways of using navigateToUrl
  2. singleSpa.navigateToUrl('/new-url');
  3. singleSpa.navigateToUrl(document.querySelector('a'));
  4. document.querySelector('a').addEventListener(singleSpa.navigateToUrl);
  1. <!-- A fourth way to use navigateToUrl, this one inside of your HTML -->
  2. <a href="/new-url" onclick="singleSpaNavigate(event)">My link</a>

Use this utility function to easily perform url navigation between registered applications without needing to deal with event.preventDefault(), pushState, triggerAppChange(), etc.

arguments

navigationObj: string | context | DOMEvent

navigationObj must be one of the following types:

  • a url string.
  • a context / thisArg that has an href property; useful for calling singleSpaNavigate.call(anchorElement) with a reference to the anchor element or other context.
  • a DOMEvent object for a click event on a DOMElement that has an href attribute; ideal for the <a onclick="singleSpaNavigate"></a> use case.

returns

undefined

  1. const mountedAppNames = singleSpa.getMountedApps();
  2. console.log(mountedAppNames); // ['app1', 'app2', 'navbar']

arguments

none

returns

appNames: string[]

Each string is the name of a registered application that is currently MOUNTED.

  1. const appNames = singleSpa.getAppNames();
  2. console.log(appNames); // ['app1', 'app2', 'app3', 'navbar']

arguments

none

returns

appNames: string[]

Each string is the name of a registered application regardless of app status.

  1. const status = singleSpa.getAppStatus('app1');
  2. console.log(status); // one of many statuses (see list below). e.g. MOUNTED

arguments

appName: string

Registered application name.

returns

appStatus: <string | null>

Will be one of the following string constants, or null if the app does not exist.- NOT_LOADED

  1. app has been registered with single-spa but has not yet been loaded.
  2. LOADING\_SOURCE\_CODE
  3. app's source code is being fetched.
  4. NOT\_BOOTSTRAPPED
  5. app has been loaded but not bootstrapped.
  6. BOOTSTRAPPING
  7. the `bootstrap` lifecycle function has been called but has not finished.
  8. NOT\_MOUNTED
  9. app has been loaded and bootstrapped but not yet mounted.
  10. MOUNTING
  11. app is being mounted but not finished.
  12. MOUNTED
  13. app is currently active and is mounted to the DOM.
  14. UNMOUNTING
  15. app is currently being unmounted but has not finished.
  16. UNLOADING
  17. app is currently being unloaded but has not finished.
  18. SKIP\_BECAUSE\_BROKEN
  19. app threw an error during load, bootstrap, mount, or unmount and has been siloed because it is misbehaving and has been skipped. Other apps will continue on normally.
  20. LOAD\_ERROR
  21. The app's loading function returned a promise that rejected. This is often due to a network error attempting to download the JavaScript bundle for the application. Single-spa will retry loading the application after the user navigates away from the current route and then comes back to it.

If a module fails to load (for example, due to network error), single-spa will handle the error but SystemJS will not automatically retry to download the module later. To do so, add a single-spa errorHandler that deletes the module from the SystemJS registry and re-attempt to download the module when System.import() on an application in LOAD_ERROR status is called again.

  1. singleSpa.addErrorHandler(err => {
  2. if (singleSpa.getAppStatus(err.appOrParcelName) === singleSpa.LOAD_ERROR) {
  3. System.delete(System.resolve(err.appOrParcelName));
  4. }
  5. });
  1. // Unload the application right now, without waiting for it to naturally unmount.
  2. singleSpa.unloadApplication('app1');
  3. // Unload the application only after it naturally unmounts due to a route change.
  4. singleSpa.unloadApplication('app1', { waitForUnmount: true });

The purpose of unloading a registered application is to set it back to a NOT_LOADED status, which means that it will be re-bootstrapped the next time it needs to mount. The main use-case for this was to allow for the hot-reloading of entire registered applications, but unloadApplication can be useful whenever you want to re-bootstrap your application.

Single-spa performs the following steps when unloadApplication is called.

  1. Call the unload lifecyle on the registered application that is being unloaded.
  2. Set the app status to NOT_LOADED
  3. Trigger a reroute, during which single-spa will potentially mount the application that was just unloaded.

Because a registered application might be mounted when unloadApplication is called, you can specify whether you want to immediately unload or if you want to wait until the application is no longer mounted. This is done with the waitForUnmount option.

arguments

appName: string

Registered application name.

options?: {waitForUnmount: boolean = false}

The options must be an object that has a waitForUnmount property. When waitForUnmount is false, single-spa immediately unloads the specified registered application even if the app is currently mounted. If it is true, single-spa will unload the registered application as soon as it is safe to do so (when the app status is not MOUNTED).

returns

Promise

This promise will be resolved when the registered application has been successfully unloaded.

  1. import { unregisterApplication } from 'single-spa';
  2. unregisterApplication('app1').then(() => {
  3. console.log('app1 is now unmounted, unloaded, and no longer registered!');
  4. });

The unregisterApplication function will unmount, unload, and unregister an application. Once it is no longer registered, the application will never again be mounted.

This api was introduced in single-spa@5.8.0. A few notes about this api:

  • Unregistering an application does not delete it from the SystemJS module registry.
  • Unregistering an application does not delete its code or javascript frameworks from browser memory.
  • An alternative to unregistering applications is to perform permission checks inside of the application’s activity function. This has a similar effect of preventing the application from ever mounting.

arguments

appName: string

returns

Promise

This promise will be resolved when the application has been successfully unregistered.

  1. const appsThatShouldBeActive = singleSpa.checkActivityFunctions();
  2. console.log(appsThatShouldBeActive); // ['app1']
  3. const appsForACertainRoute = singleSpa.checkActivityFunctions(new URL('/app2', window.location.href));
  4. console.log(appsForACertainRoute); // ['app2']

Will call every app’s activity function with url and give you list of which applications should be mounted with that location.

arguments

url: URL

A URL object that will be used instead of window.location when calling every application’s activity function to test if they return true.

returns

appNames: string[]

Each string is the name of a registered application that matches the provided url.

  1. singleSpa.addErrorHandler(err => {
  2. console.log(err);
  3. console.log(err.appOrParcelName);
  4. console.log(singleSpa.getAppStatus(err.appOrParcelName));
  5. });

Adds a handler that will be called every time an application throws an error during a lifecycle function or activity function. When there are no error handlers, single-spa throws the error to the window.

errorHandler: Function(error: Error)

Must be a function. Will be called with an Error object that additionally has a message and appOrParcelName property.

returns

undefined

  1. singleSpa.addErrorHandler(handleErr);
  2. singleSpa.removeErrorHandler(handleErr);
  3. function handleErr(err) {
  4. console.log(err);
  5. }

Removes the given error handler function.

arguments

errorHandler: Function

Reference to the error handling function.

returns

boolean

true if the error handler was removed, and false if it was not.

  1. // Synchronous mounting
  2. const parcel = singleSpa.mountRootParcel(parcelConfig, {
  3. prop1: 'value1',
  4. domElement: document.getElementById('a-div'),
  5. });
  6. parcel.mountPromise.then(() => {
  7. console.log('finished mounting the parcel!');
  8. });
  9. // Asynchronous mounting. Feel free to use webpack code splits or SystemJS dynamic loading
  10. const parcel2 = singleSpa.mountRootParcel(() => import('./some-parcel.js'), {
  11. prop1: 'value1',
  12. domElement: document.getElementById('a-div'),
  13. });

Will create and mount a single-spa parcel.

Applications API - 图2Parcels do not automatically unmount

Unmounting will need to be triggered manually.

arguments

parcelConfig: Object or Loading Function

[parcelConfig](/docs/parcels-api#parcel-configuration)

parcelProps: Object with a domElement property

[parcelProps](/docs/parcels-api#parcel-props)

returns

Parcel object

See Parcels API for more detail.

The pathToActiveWhen function converts a string URL path into an activity function. The string path may contain route parameters that single-spa will match any characters to. By default, pathToActiveWhen assumes that the string provided is a prefix; however, this can be altered with the exactMatch parameter.

This function is used by single-spa when a string is passed into registerApplication as the activeWhen argument.

Arguments

  1. path (string): The URL prefix that.
  2. exactMatch (boolean, optional, defaults to false, requires single-spa@>=5.9.0): A boolean that controls whether trailing characters after the path should be allowed. When false, trailing characters are allowed. When true, trailing characters are not allowed.

Return Value

(url: URL) => boolean

A function that accepts a URL object as an argument and returns a boolean indicating whether the path matches that URL.

Examples:

  1. let activeWhen = singleSpa.pathToActiveWhen('/settings');
  2. activeWhen(new URL('http://localhost/settings')); // true
  3. activeWhen(new URL('http://localhost/settings/password')); // true
  4. activeWhen(new URL('http://localhost/')); // false
  5. activeWhen = singleSpa.pathToActiveWhen('/users/:id/settings');
  6. activeWhen(new URL('http://localhost/users/6f7dsdf8g9df8g9dfg/settings')); // true
  7. activeWhen(new URL('http://localhost/users/1324/settings')); // true
  8. activeWhen(new URL('http://localhost/users/1324/settings/password')); // true
  9. activeWhen(new URL('http://localhost/users/1/settings')); // true
  10. activeWhen(new URL('http://localhost/users/1')); // false
  11. activeWhen(new URL('http://localhost/settings')); // false
  12. activeWhen(new URL('http://localhost/')); // false
  13. activeWhen = singleSpa.pathToActiveWhen('/page#/hash');
  14. activeWhen(new URL('http://localhost/page#/hash')); // true
  15. activeWhen(new URL('http://localhost/#/hash')); // false
  16. activeWhen(new URL('http://localhost/page')); // false
  1. singleSpa.ensureJQuerySupport(jQuery);

jQuery uses event delegation so single-spa must monkey-patch each version of jQuery on the page. single-spa will attempt to do this automatically by looking for window.jQuery or window.$. Use this explicit method if multiple versions are included on your page or if jQuery is bound to a different global variable.

arguments

jQuery?: JQueryFn = window.jQuery

A reference to the global variable that jQuery has been bound to.

returns

undefined

  1. // After three seconds, show a console warning while continuing to wait.
  2. singleSpa.setBootstrapMaxTime(3000);
  3. // After three seconds, move the application to SKIP_BECAUSE_BROKEN status.
  4. singleSpa.setBootstrapMaxTime(3000, true);
  5. // don't do a console warning for slow lifecycles until 10 seconds have elapsed
  6. singleSpa.setBootstrapMaxTime(3000, true, 10000);

Sets the global configuration for bootstrap timeouts.

arguments

millis: number

Number of milliseconds to wait for bootstrap to complete before timing out.

dieOnTimeout: boolean = false

If false, registered applications that are slowing things down will cause nothing more than some warnings in the console up until millis is reached.

If true, registered applications that are slowing things down will be siloed into a SKIP_BECAUSE_BROKEN status where they will never again be given the chance to break everything.

Each registered application can override this behavior for itself.

warningMillis: number = 1000

Number of milliseconds to wait between console warnings that occur before the final timeout.

returns

undefined

  1. // After three seconds, show a console warning while continuing to wait.
  2. singleSpa.setMountMaxTime(3000);
  3. // After three seconds, move the application to SKIP_BECAUSE_BROKEN status.
  4. singleSpa.setMountMaxTime(3000, true);
  5. // don't do a console warning for slow lifecycles until 10 seconds have elapsed
  6. singleSpa.setMountMaxTime(3000, true, 10000);

Sets the global configuration for mount timeouts.

arguments

millis: number

Number of milliseconds to wait for mount to complete before timing out.

dieOnTimeout: boolean = false

If false, registered applications that are slowing things down will cause nothing more than some warnings in the console up until millis is reached.

If true, registered applications that are slowing things down will be siloed into a SKIP_BECAUSE_BROKEN status where they will never again be given the chance to break everything.

Each registered application can override this behavior for itself.

warningMillis: number = 1000

Number of milliseconds to wait between console warnings that occur before the final timeout.

returns

undefined

  1. // After three seconds, show a console warning while continuing to wait.
  2. singleSpa.setUnmountMaxTime(3000);
  3. // After three seconds, move the application to SKIP_BECAUSE_BROKEN status.
  4. singleSpa.setUnmountMaxTime(3000, true);
  5. // don't do a console warning for slow lifecycles until 10 seconds have elapsed
  6. singleSpa.setUnmountMaxTime(3000, true, 10000);

Sets the global configuration for unmount timeouts.

arguments

millis: number

Number of milliseconds to wait for unmount to complete before timing out.

dieOnTimeout: boolean = false

If false, registered applications that are slowing things down will cause nothing more than some warnings in the console up until millis is reached.

If true, registered applications that are slowing things down will be siloed into a SKIP_BECAUSE_BROKEN status where they will never again be given the chance to break everything.

Each registered application can override this behavior for itself.

warningMillis: number = 1000

Number of milliseconds to wait between console warnings that occur before the final timeout.

returns

undefined


  1. // After three seconds, show a console warning while continuing to wait.
  2. singleSpa.setUnloadMaxTime(3000);
  3. // After three seconds, move the application to SKIP_BECAUSE_BROKEN status.
  4. singleSpa.setUnloadMaxTime(3000, true);
  5. // don't do a console warning for slow lifecycles until 10 seconds have elapsed
  6. singleSpa.setUnloadMaxTime(3000, true, 10000);

Sets the global configuration for unload timeouts.

arguments

millis: number

Number of milliseconds to wait for unload to complete before timing out.

dieOnTimeout: boolean = false

If false, registered applications that are slowing things down will cause nothing more than some warnings in the console up until millis is reached.

If true, registered applications that are slowing things down will be siloed into a SKIP_BECAUSE_BROKEN status where they will never again be given the chance to break everything.

Each registered application can override this behavior for itself.

warningMillis: number = 1000

Number of milliseconds to wait between console warnings that occur before the final timeout.

returns

undefined

single-spa fires Events to the window as a way for your code to hook into URL transitions.

single-spa fires PopStateEvent events when it wants to instruct all active applications to re-render. This occurs when one application calls history.pushState, history.replaceState, or triggerAppChange. Single-spa deviates from the browser’s default behavior in some cases, as described in this Github issue.

  1. window.addEventListener('popstate', evt => {
  2. if (evt.singleSpa) {
  3. console.log(
  4. 'This event was fired by single-spa to forcibly trigger a re-render',
  5. );
  6. console.log(evt.singleSpaTrigger); // pushState | replaceState
  7. } else {
  8. console.log('This event was fired by native browser behavior');
  9. }
  10. });

Canceling navigation refers to the URL changing and then immediately changing back to what it was before. This is done before any mounting, unmounting, or loading that would otherwise take place. This can be used in conjunction with Vue router and Angular router’s built-in navigation guards that allow for cancelation of a navigation event.

To cancel a navigation event, listen to the single-spa:before-routing-event event:

  1. window.addEventListener(
  2. 'single-spa:before-routing-event',
  3. ({ detail: { oldUrl, newUrl, cancelNavigation } }) => {
  4. if (
  5. new URL(oldUrl).pathname === '/route1' &&
  6. new URL(newUrl).pathname === '/route2'
  7. ) {
  8. cancelNavigation();
  9. }
  10. },
  11. );

When a navigation is canceled, no applications will be mounted, unmounted, loaded, or unloaded. All single-spa routing events will fire for the canceled navigation, but they will each have the navigationIsCanceled property set to true on the event.detail (Details below in Custom Events section).

Navigation cancelation is sometimes used as a mechanism for preventing users from accessing routes for which they are unauthorized. However, we generally recommend permission checks on each route as the proper way to guard routes, instead of navigation cancelation.

single-spa fires a series of custom events whenever it reroutes. A reroute occurs whenever the browser URL changes in any way or a triggerAppChange is called. The custom events are fired to the window. Each custom event has a detail property with the following properties:

  1. window.addEventListener('single-spa:before-routing-event', evt => {
  2. const {
  3. originalEvent,
  4. newAppStatuses,
  5. appsByNewStatus,
  6. totalAppChanges,
  7. oldUrl,
  8. newUrl,
  9. navigationIsCanceled,
  10. cancelNavigation,
  11. } = evt.detail;
  12. console.log(
  13. 'original event that triggered this single-spa event',
  14. originalEvent,
  15. ); // PopStateEvent | HashChangeEvent | undefined
  16. console.log(
  17. 'the new status for all applications after the reroute finishes',
  18. newAppStatuses,
  19. ); // { app1: MOUNTED, app2: NOT_MOUNTED }
  20. console.log(
  21. 'the applications that changed, grouped by their status',
  22. appsByNewStatus,
  23. ); // { MOUNTED: ['app1'], NOT_MOUNTED: ['app2'] }
  24. console.log(
  25. 'number of applications that changed status so far during this reroute',
  26. totalAppChanges,
  27. ); // 2
  28. console.log('the URL before the navigationEvent', oldUrl); // http://localhost:8080/old-route
  29. console.log('the URL after the navigationEvent', newUrl); // http://localhost:8080/new-route
  30. console.log('has the navigation been canceled', navigationIsCanceled); // false
  31. // The cancelNavigation function is only defined in the before-routing-event
  32. evt.detail.cancelNavigation();
  33. });

The following table shows the order in which the custom events are fired during a reroute:

Event orderEvent NameCondition for firing
1single-spa:before-app-change or single-spa:before-no-app-changeWill any applications change status?
2single-spa:before-routing-event
3single-spa:before-mount-routing-event
4single-spa:before-first-mountIs this the first time any application is mounting?
5single-spa:first-mountIs this the first time any application was mounted?
6single-spa:app-change or single-spa:no-app-changeDid any applications change status?
7single-spa:routing-event
  1. window.addEventListener('single-spa:before-app-change', evt => {
  2. console.log('single-spa is about to mount/unmount applications!');
  3. console.log(evt.detail.originalEvent); // PopStateEvent
  4. console.log(evt.detail.newAppStatuses); // { app1: MOUNTED }
  5. console.log(evt.detail.appsByNewStatus); // { MOUNTED: ['app1'], NOT_MOUNTED: [] }
  6. console.log(evt.detail.totalAppChanges); // 1
  7. });

A single-spa:before-app-change event is fired before reroutes that will result in at least one application changing status.

  1. window.addEventListener('single-spa:before-no-app-change', evt => {
  2. console.log('single-spa is about to do a no-op reroute');
  3. console.log(evt.detail.originalEvent); // PopStateEvent
  4. console.log(evt.detail.newAppStatuses); // { }
  5. console.log(evt.detail.appsByNewStatus); // { MOUNTED: [], NOT_MOUNTED: [] }
  6. console.log(evt.detail.totalAppChanges); // 0
  7. });

A single-spa:before-no-app-change event is fired before reroutes that will result in zero applications changing status.

  1. window.addEventListener('single-spa:before-routing-event', evt => {
  2. console.log('single-spa is about to mount/unmount applications!');
  3. console.log(evt.detail.originalEvent); // PopStateEvent
  4. console.log(evt.detail.newAppStatuses); // { }
  5. console.log(evt.detail.appsByNewStatus); // { MOUNTED: [], NOT_MOUNTED: [] }
  6. console.log(evt.detail.totalAppChanges); // 0
  7. });

A single-spa:before-routing-event event is fired before every routing event occurs, which is after each hashchange, popstate, or triggerAppChange, even if no changes to registered applications were necessary.

  1. window.addEventListener('single-spa:before-mount-routing-event', evt => {
  2. console.log('single-spa is about to mount/unmount applications!');
  3. console.log(evt.detail);
  4. console.log(evt.detail.originalEvent); // PopStateEvent
  5. console.log(evt.detail.newAppStatuses); // { app1: MOUNTED }
  6. console.log(evt.detail.appsByNewStatus); // { MOUNTED: ['app1'], NOT_MOUNTED: [] }
  7. console.log(evt.detail.totalAppChanges); // 1
  8. });

A single-spa:before-mount-routing-event event is fired after before-routing-event and before routing-event. It is guaranteed to fire after all single-spa applications have been unmounted, but before any new applications have been mounted.

  1. window.addEventListener('single-spa:before-first-mount', () => {
  2. console.log(
  3. 'single-spa is about to mount the very first application for the first time',
  4. );
  5. });

Before the first of any single-spa applications is mounted, single-spa fires a single-spa:before-first-mount event; therefore it will only be fired once ever. More specifically, it fires after the application is already loaded but before mounting.

Applications API - 图3Suggested use case

remove a loader bar that the user is seeing right before the first app will be mounted.

  1. window.addEventListener('single-spa:first-mount', () => {
  2. console.log('single-spa just mounted the very first application');
  3. });

After the first of any single-spa applications is mounted, single-spa fires a single-spa:first-mount event; therefore it will only be fired once ever.

Applications API - 图4Suggested use case

log the time it took before the user sees any of the apps mounted.

  1. window.addEventListener('single-spa:app-change', evt => {
  2. console.log(
  3. 'A routing event occurred where at least one application was mounted/unmounted',
  4. );
  5. console.log(evt.detail.originalEvent); // PopStateEvent
  6. console.log(evt.detail.newAppStatuses); // { app1: MOUNTED, app2: NOT_MOUNTED }
  7. console.log(evt.detail.appsByNewStatus); // { MOUNTED: ['app1'], NOT_MOUNTED: ['app2'] }
  8. console.log(evt.detail.totalAppChanges); // 2
  9. });

A single-spa:app-change event is fired every time that one or more apps were loaded, bootstrapped, mounted, unmounted, or unloaded. It is similar to single-spa:routing-event except that it will not fire unless one or more apps were actually loaded, bootstrapped, mounted, or unmounted. A hashchange, popstate, or triggerAppChange that does not result in one of those changes will not cause the event to be fired.

  1. window.addEventListener('single-spa:no-app-change', evt => {
  2. console.log(
  3. 'A routing event occurred where zero applications were mounted/unmounted',
  4. );
  5. console.log(evt.detail.originalEvent); // PopStateEvent
  6. console.log(evt.detail.newAppStatuses); // { }
  7. console.log(evt.detail.appsByNewStatus); // { MOUNTED: [], NOT_MOUNTED: [] }
  8. console.log(evt.detail.totalAppChanges); // 0
  9. });

When no applications were loaded, bootstrapped, mounted, unmounted, or unloaded, single-spa fires a single-spa:no-app-change event. This is the inverse of the single-spa:app-change event. Only one will be fired for each routing event.

  1. window.addEventListener('single-spa:routing-event', evt => {
  2. console.log('single-spa finished mounting/unmounting applications!');
  3. console.log(evt.detail.originalEvent); // PopStateEvent
  4. console.log(evt.detail.newAppStatuses); // { app1: MOUNTED, app2: NOT_MOUNTED }
  5. console.log(evt.detail.appsByNewStatus); // { MOUNTED: ['app1'], NOT_MOUNTED: ['app2'] }
  6. console.log(evt.detail.totalAppChanges); // 2
  7. });

A single-spa:routing-event event is fired every time that a routing event has occurred, which is after each hashchange, popstate, or triggerAppChange, even if no changes to registered applications were necessary; and after single-spa verified that all apps were correctly loaded, bootstrapped, mounted, and unmounted.

Applications API - 图5Edit this page