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 reuses unmounted instances by app name. 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. Keep app names stable

When the same app mounts again, qiankun looks for a reusable instance by name and entry. A cache hit skips entry execution and bootstrap, even with a newly created container node; if the cache entry was reclaimed and no other instance can be reused, qiankun reloads the app. A name should always refer to the same app; do not generate a different name on every render. See Run multiple micro-app instances for idle pool capacity and time limits.

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

4. Create per-mount state inside mount

A remount may reuse a cached instance or reload after reclamation. Create the application instance, router, and per-instance store inside mount(), then destroy them in unmount(), rather than depending on how many times module top-level code executes. 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.