Micro-app lifecycle and props

loadMicroApp connects two public contracts: the micro-app exports lifecycle functions, and the host receives a MicroApp handle that controls the running instance. Keeping both sides explicit makes an app safe to mount, update, unmount, and mount again.

Implementation details about export resolution and hook ordering live in Lifecycle resolution internals.

The micro-app contract

Every micro-app exposes bootstrap, mount, and unmount. update is optional:

import type { BootstrapContext } from 'qiankun';

type HostProps = {
  accountId: string;
};

type MountProps = HostProps & { container: HTMLElement };

export async function bootstrap(context: BootstrapContext) {
  // context contains only the current application's name and entry, without business props or a container.
  // Initialize code that does not depend on the mount location or user state here.
}

export async function mount(props: MountProps) {
  // Create and render the UI inside props.container.
}

export async function update(props: HostProps) {
  // Apply host-driven changes without remounting.
}

export async function unmount(props: MountProps) {
  // Destroy the UI created by mount and release its resources.
}

Native ESM apps can use named exports as above or export one default lifecycle object. Classic builds expose the same object through their bundler output. The Vite and Webpack guides provide working configurations.

The host controls the handle

loadMicroApp starts the first mount automatically and returns immediately. Keep the handle for status, updates, and teardown:

const microApp = loadMicroApp({
  name: 'account-app',
  entry: 'https://accounts.example.com/',
  container,
  props: { accountId: '42' },
});

await microApp.mountPromise;

if (microApp.update) {
  await microApp.update({ accountId: '84' });
}

await microApp.unmount();

// The same handle can be mounted again when needed.
await microApp.mount();

The update method is present only when the micro-app exports update. If the application does not support in-place updates, unmount it and create or mount the appropriate instance instead.

Bootstrap initialization context

bootstrap runs initialization that does not depend on mount location or application state. Read mutable user, route, or theme data inside mount or update.

Create framework roots, router instances, and view state in mount, and destroy them in unmount.

bootstrap receives only BootstrapContext, a readonly { name, entry } object. qiankun constructs and freezes it separately, without passing in business props, a container, or single-spa mount capabilities.

Props, the container, and host hooks

The host's props are passed to the micro-app's mount, unmount, and optional update. For mount and unmount, qiankun also supplies props.container, the actual HTMLElement owned by this instance.

Render and query within that container. Do not mount through a page-global selector: it breaks multiple instances and couples the micro-app to the host's document structure. Treat the container as instance-scoped; the micro-app must stop using it after unmount, even if the host later reuses it.

Props are also the simplest explicit channel for callbacks, shared services, and host-owned state. For longer-lived communication patterns, see Share state and communicate between apps.

Host lifecycle hooks (beforeLoad, beforeMount, afterMount, beforeUnmount, afterUnmount) are a separate API for observing transitions around the micro-app. Use the Lifecycle hooks reference when the host needs logging, loading indicators, or policy checks; keep rendering and cleanup in the micro-app's own lifecycles.

Mount, unmount, and remount

• bootstrap runs once before the first mount after the micro-app code is loaded. Reusing an existing instance skips it; reloading after cache reclamation runs it again.
• mount creates the visible application and may run more than once.
• unmount must reverse every user-visible effect created by mount.
• update, when exported, applies new host props to an already mounted instance.

On remount, qiankun rebuilds the entry DOM and calls mount again. A cache hit does not re-run entry scripts or module top-level code; reloading after cache reclamation runs the entry and bootstrap again. Create disposable framework roots and view state inside mount, then destroy them inside unmount, rather than depending on how many times top-level code executes. See Run multiple micro-app instances for the cache policy.

Cleanup is a shared responsibility

qiankun deactivates the sandbox and clears the instance container after the micro-app's unmount completes. The micro-app must still clean up anything it created outside that DOM tree, including:

• framework roots and portals;
• subscriptions to host stores or event buses;
• pending requests, workers, observers, and other external resources;
• references retained by host-provided callbacks or services.

Always observe the Promise returned by unmount(). Await it before removing the container when the owning flow can pause; when a framework cleanup callback cannot await, start unmounting and attach a rejection handler before dropping the handle. A well-formed lifecycle should tolerate repeated mount/unmount cycles without duplicated listeners or stale UI.

The loaded instance is kept after unmounting for reuse by the same app; call unload() to release it. Disposal revokes the membrane, so the micro-app should also clear pending timers and asynchronous callbacks in unmount. See loadMicroApp.

For URL-driven activation, registerMicroApps uses the same micro-app contract but lets routing decide when mount and unmount occur.

Continue reading

• loadMicroApp — complete handle and promise reference.
• Loading a micro-app instance — the surrounding runtime model.
• Run multiple instances — container and instance patterns.
• Lifecycle resolution internals — export discovery and hook ordering for maintainers.