Optimize micro-app loading

qiankun processes HTML Entries as streams and discovers later resources while loading. Most applications do not need a prefetch strategy. Effective improvements usually come from entry size, HTTP caching, CORS, and stable mounting behavior.

Establish a baseline

Measure the mount time users actually experience around loadMicroApp and its mountPromise:

performance.mark('sub-app:start');

const microApp = loadMicroApp({
  name: 'sub-app',
  entry: '//localhost:7101',
  container,
});

await microApp.mountPromise;
performance.measure('sub-app:mount', 'sub-app:start');

Record both a first load and a later remount in the browser Network panel. Do not compare only the HTML Entry download time.

Optimize in this order

1. Configure CORS and HTTP caching

The host fetches the micro-app entry and assets, so cross-origin servers must return appropriate CORS headers.

Use long-lived caching for hashed JavaScript, CSS, and font assets. Give the HTML Entry a policy that allows revalidation without hiding new deployments. Ensure compression and CDN delivery cover micro-app assets too.

qiankun also keeps successful fetches in a page-scoped in-memory LRU cache and can reuse the lifecycle configuration for the same app and container. HTTP revalidation applies when that runtime cache misses; remounting in the same page is not a deployment-refresh mechanism. Reload the host page when it must pick up a newly deployed micro-app version.

2. Keep the HTML Entry focused

The entry should declare only resources needed by this app and contain at most one script marked as the entry. Production builds generated by the official bundler plugin normally contain one marked entry script; Vite development HTML may omit the explicit marker because qiankun can select the lifecycle module at runtime.

3. Reuse a stable container

When the same app returns to the same container, qiankun can reuse work that has already completed. Framework components should not replace the container node unnecessarily on every render. When calling loadMicroApp directly, reuse a stable element for the same display region.

For concurrent instances, give every instance its own container and follow the multiple-instances guide.

4. Create per-mount state inside mount

Do not rely on module top-level code running again on remount. Create the application instance, router, and per-instance store inside mount(), then destroy them in unmount(). Reusing loaded work will then not preserve stale state or lose mount-time effects.

5. Override fetch carefully

Provide a custom fetch only when authentication, proxying, or observability requires it. Preserve the standard Fetch API response and streaming semantics; do not consume the response into a string early or discard cache headers.

See AppConfiguration.fetch for the complete field reference.

Do not port 2.x prefetch configuration

• Do not call start({ prefetch: ... }); v3 start() does not accept that configuration.
• prefetchApps is deprecated and should not be a default optimization for new projects.
• Do not create a loadMicroApp instance that is never unmounted merely to warm resources.

Only consider product-level early loading after measurements show that normal on-demand loading misses the target, and design cancellation and teardown at the same time.

Diagnose with the Network panel

Check in this order:

1. Whether redirects, authentication, or CORS block the HTML Entry.
2. Whether critical JavaScript and CSS lack compression or useful cache headers.
3. Whether duplicate downloads, oversized source maps, or unrelated assets dominate the waterfall.
4. Whether a remount still causes a complete network waterfall.
5. Whether mountPromise time is spent on the network, script execution, or the micro-app's own rendering.

When the network is fast but mountPromise remains slow, optimize the micro-app startup and first render rather than the qiankun loader.

Related

• HTML Entry and execution — the user-visible loading model.
• Handle load and runtime errors — surface resource failures.
• AppConfiguration — custom fetch and advanced options.
• Streaming HTML Entry internals — contributor-level implementation detail.