Qiankun — Micro-Frontend Framework for Enterprise Apps

Introduction

Qiankun is a micro-frontend framework built on top of single-spa, developed by the Ant Group UmiJS team. It allows multiple independently built and deployed front-end applications to coexist on a single page. Qiankun handles application loading, sandboxing, and inter-app communication, making it practical for large organizations that need to integrate apps built with different frameworks.

What Qiankun Does

• Loads and mounts sub-applications dynamically based on URL routing rules
• Provides JavaScript sandbox isolation so sub-apps do not pollute the global scope
• Offers CSS isolation via shadow DOM or scoped style prefixing
• Supports prefetching sub-application resources for faster navigation
• Enables parent-child communication through a global state API

Architecture Overview

Qiankun wraps single-spa's lifecycle management with additional features for sandboxing and resource loading. When a route matches, qiankun fetches the sub-app's HTML entry, parses out scripts and styles, and executes them inside a proxy-based JavaScript sandbox. Each sub-app gets its own faux-global window object. CSS isolation is achieved by either wrapping styles in a shadow DOM or automatically prefixing selectors.

Self-Hosting & Configuration

• Install qiankun in the main (shell) application; sub-apps export lifecycle hooks (bootstrap, mount, unmount)
• Configure each sub-app with a name, entry URL, container DOM selector, and activeRule
• Enable prefetch by passing prefetch: true to the start() options for background loading
• Use the sandbox option to choose between proxy-based or snapshot-based JS isolation
• Set experimentalStyleIsolation for automatic CSS scoping without shadow DOM

Key Features

• Framework-agnostic: sub-apps can be React, Vue, Angular, or vanilla JS
• HTML entry loading: fetches the sub-app's index.html directly, no build-time integration required
• Global state management for cross-app communication via initGlobalState
• Support for multiple sub-apps running simultaneously on the same page
• Compatible with Webpack Module Federation for hybrid architectures

Comparison with Similar Tools

• single-spa — lower-level foundation; qiankun adds sandboxing, CSS isolation, and HTML entry loading
• Module Federation — build-time sharing of modules; qiankun is runtime-based and framework-agnostic
• Garfish (ByteDance) — similar runtime micro-frontend solution with its own sandbox implementation
• Piral — extension-based micro-frontend framework for React; qiankun is framework-agnostic
• Luigi (SAP) — iframe-based micro-frontend framework; qiankun uses in-page rendering for better UX

FAQ

Q: Do sub-apps need to be modified to work with qiankun? A: Sub-apps must export three lifecycle functions (bootstrap, mount, unmount) and configure their bundler to output a UMD or library format.

Q: How does the JavaScript sandbox work? A: Qiankun creates a Proxy-based faux window for each sub-app, intercepting global variable reads and writes to prevent cross-app contamination.

Q: Can I run multiple sub-apps at the same time? A: Yes. Use loadMicroApp() for manual mounting of multiple apps on different DOM containers simultaneously.

Q: Does qiankun support SSR? A: Partial support. The shell app can be SSR-rendered, but sub-apps are loaded client-side.

Sources

• https://github.com/umijs/qiankun
• https://qiankun.umijs.org