# Qiankun — Micro-Frontend Framework for Enterprise Apps

> A production-ready micro-frontend solution built on single-spa that lets you compose independently deployed sub-applications into a unified shell.

## Install

Save in your project root:

# Qiankun — Micro-Frontend Framework for Enterprise Apps

## Quick Use
```bash
npm install qiankun
```
```js
import { registerMicroApps, start } from 'qiankun'
registerMicroApps([
  { name: 'app1', entry: '//localhost:8081', container: '#container', activeRule: '/app1' },
])
start()
```

## 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

---
Source: https://tokrepo.com/en/workflows/asset-33883ba1
Author: AI Open Source