# qiankun 3.0: HTML entry, a Proxy sandbox and where the rc tag stands

> qiankun is an MIT-licensed micro frontend framework built on single-spa, and version 3.0 is shipping under the rc tag. Here is what the mechanism actually does, how to install it, and which parts the README leaves open.

**umijs/qiankun** — 📦 🚀 Blazing fast, simple and complete solution for micro frontends.

- Repository: https://github.com/umijs/qiankun
- Website: https://qiankun.umijs.org
- Stars: 16,691 · Forks: 2,061
- Language: TypeScript
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/umijs-qiankun

## What qiankun solves, and for whom

The README frames the origin plainly: the framework grew out of internal work where web development by distributed teams had turned chaotic, and the team extracted what it calls the minimal viable framework of its solution. The audience is therefore a group of teams that deploy independently, often on different JavaScript frameworks, and need one page to compose their output. The README quotes the micro frontends definition it works from: techniques for building a modern web app with multiple teams using different JavaScript frameworks. qiankun does not try to be a build system or a design system. It takes over one job, which is mounting another team's deployed application into a container element inside your page, and unmounting it cleanly when that part of the page goes away. If you are one team splitting a single SPA into folders, the problem qiankun was built for is not your problem, and the sandbox and lifecycle contract are overhead you would be paying for nothing.

## HTML entry, the Proxy membrane, and the three-hook contract

The architectural choice that separates qiankun from a manifest-driven loader is HTML entry. You point it at a URL rather than a list of assets. The README states that the entry is streamed into the live document as it arrives, so a micro app starts rendering before its HTML has finished downloading. That is the data flow: a URL goes in, qiankun fetches the document, and the document's own script and style tags decide what loads. Everything else follows from that.

The second mechanism is the JS sandbox, on by default. Each micro app runs against a Proxy-membrane view of window and document, so globals, timers, listeners and dynamically inserted DOM stay inside the app and are reclaimed on unmount. This is a runtime containment strategy, not a build-time one. The README also notes native ESM support: script tags with type="module" execute as real modules, routed through the membrane with dynamically injected import maps, and dynamic import() works, which is what makes a Vite dev server usable.

The third piece is the contract a micro app must satisfy. It exports bootstrap, mount and unmount. The README calls that the whole contract, and the mount hook receives props containing the container element. That is a deliberately small surface: qiankun does not own your rendering library, and the README states the host never dictates a micro app's stack.

## Installing qiankun 3.0 and loading a first micro app

The README carries a warning worth reading before any command: v3 ships under the rc tag while latest still points at 2.x, so an explicit @rc is required. The repository's most recent release at the time of writing is v3.0.0-rc.22, published on 2026-08-30. The last push to the default branch, next, was on 2026-09-17.

The README offers a second install path aimed at coding agents, which scaffolds a host or a micro app wired up correctly. If you use Claude Code or Cursor, the README gives this:

```shell
npx skills add umijs/qiankun
```

For a host application you already have, the package install is:

```shell
npm i qiankun@rc
```

Then load a micro app into a container element and keep the returned handle. The README's example uses a name, an entry URL and a container:

```ts
import { loadMicroApp } from 'qiankun';

const microApp = loadMicroApp({
  name: 'react-app',
  entry: '//localhost:7100',
  container: document.getElementById('subapp-container'),
});

// when this part of the page goes away:
await microApp.unmount();
```

What you should see is the micro app's own HTML streaming into that container and its scripts executing inside the sandbox. The README notes that if a micro app's activation is fully determined by the URL, registerMicroApps plus start is the alternative orchestration model, and that the quick start page documents the bundler configuration each stack needs. That last sentence is the part to take seriously: the framework's own examples directory contains separate React, Vue, Vue host, webpack, purehtml and streaming setups, which suggests the per-stack wiring is not uniform.

## Style isolation depends on @scope, and that is a real constraint

qiankun's style isolation is opt-in and built on the CSS @scope at-rule, including for external stylesheets. The README presents this as an advantage: no rewriting your CSS, no Shadow DOM tax. That is a fair summary of the trade-off, but it moves the compatibility question to the browser. @scope is a comparatively recent CSS feature, and a project whose support matrix includes older browsers cannot rely on this path without checking. The README does not state a browser support matrix, and the documentation is silent on what happens when @scope is unavailable. If style isolation is the reason you picked qiankun, verify this against your actual target browsers before you plan the migration, because the fallback behaviour is not described in the README.

There is a second boundary worth naming. The sandbox contains globals, timers, listeners and dynamic DOM. It is a runtime membrane over window and document. It is not a security boundary between mutually untrusted parties. Nothing in the README frames it that way, and treating a Proxy membrane as a security control would be a misreading of what it is for.

## The standalone sandbox is the most underrated export

One feature in the README does not require the micro frontend framework at all. The package @qiankunjs/sandbox is described as usable on its own to contain any third-party script. That is a different product category from the rest of the repository, and it is the piece most likely to be useful to someone who has already decided against micro frontends. If you embed a vendor widget, an analytics snippet from a partner, or any script you do not control and cannot audit, the same containment mechanism applies without a host shell, a lifecycle contract, or a URL entry. The examples directory includes a standalone-sandbox folder, and the README points at a standalone sandbox lab among the deployed examples. The README does not document the standalone package's API in the sections available here, so the examples and the package directory are where you would look first.

## single-spa, Module Federation, and wujie: where the approaches diverge

qiankun is based on single-spa and inherits independent deployment, lazy loading and a technology-agnostic host from it. The difference is what qiankun adds on top: HTML entry, the JS sandbox, style isolation and prefetch. With single-spa alone you assemble an application registry and configure the loading yourself; qiankun's pitch is that the registry, the sandbox and the URL entry are already wired. If you are already running single-spa in production and it works, qiankun is not a rewrite you need, it is a set of concerns you would otherwise implement yourself.

Module Federation attacks the same problem from inside the bundler. It shares modules between separately built applications at build and runtime, with the host and remote relationship declared in bundler configuration. qiankun's approach is deliberately outside the bundler: a micro app is a deployed page reached by URL, and the framework does not need to know what built it. That is why the README can claim a host that never dictates a micro app's stack. The cost is that you get no shared module graph by default, and the README raises public dependencies as one of the problems the team faced without stating how the current version resolves it.

wujie and micro-app are the other comparison points people search for. Both are separate projects with their own isolation strategies, and this material does not describe their internals, so the honest statement is that the comparison has to be made against their own documentation rather than from anything qiankun's README provides.

## Version 2, the rc line, and what adoption costs

The version story is the first thing to settle. The README states that qiankun 3.0 is under development and links a roadmap discussion, and that qiankun 2.x documentation lives at v2.qiankun.umijs.org. The release list shows the split clearly: v2.10.16 was published on 2023-11-15, while the 3.0 line is at v3.0.0-rc.22 from 2026-08-30. Installing without a tag gives you 2.x. Installing with @rc gives you a release candidate.

The upgrade cost is not documented in the README. There is no migration guide, no list of breaking changes between 2.x and 3.0, and no rollback procedure described. For a team already on 2.10.x, that means the move to 3.0 is a project with an unknown shape until you read the v2 documentation alongside the current one. The repository does carry a .changeset directory, which is the conventional place for per-release change records, and the roadmap discussion is the stated place for direction. Neither is a substitute for a migration document, and the README does not claim to be one.

The licence is MIT, per the repository and the licence badge in the README. That is permissive and imposes no source disclosure obligation on your own application code. It says nothing about the licences of the micro apps you load, which remain separate deployed artifacts under their own terms. This is a description of the licence identifier, not legal advice; a lawyer should review anything that matters to you.

## Conclusion

Adopt qiankun when several teams own separate deployments and you want one shell to mount them by URL, and you accept that the current line is v3.0.0-rc.22 rather than a stable 3.x. Do not adopt it for a single-team SPA split into folders, and do not treat the rc tag as a drop-in for a v2 production install without reading the v2 documentation first. Verify three things before you commit: that your browser targets support the CSS @scope at-rule used for style isolation, that your bundler works with the webpack 4/5 and Vite plugin in packages/bundler-plugin, and that your micro app's build emits the entry script the plugin expects.

## FAQ

### What is qiankun?

qiankun is an MIT-licensed micro frontend framework written in TypeScript, inspired by and based on single-spa. It mounts separately deployed web applications into a container element in a host page, using a URL as the entry point rather than a manifest of assets.

### What does qiankun mean in Chinese?

The README explains that qian (乾) means heaven and kun (坤) earth, so qiankun is the universe. The name was chosen because the framework can contain and serve anything.

### How do I install qiankun?

The README gives npm i qiankun@rc for a host application, and notes that v3 ships under the rc tag while latest still points at 2.x, so the explicit tag matters. It also offers npx skills add umijs/qiankun for scaffolding through a coding agent.

### How does qiankun compare with single-spa?

qiankun is based on single-spa and inherits independent deployment, lazy loading and a technology-agnostic host from it. On top of that it adds HTML entry, a JS sandbox on by default, opt-in style isolation built on the CSS @scope at-rule, and prefetch.

### How does qiankun differ from Module Federation?

Module Federation works inside the bundler and shares a module graph between builds. qiankun stays outside the bundler: a micro app is a deployed page reached by URL, which is why the host never dictates the micro app's stack, at the cost of no shared module graph by default.

### What alternatives to qiankun should I look at?

The comparison points that come up are single-spa, Module Federation, wujie and micro-app. This material describes qiankun's own mechanism and its relationship to single-spa and Module Federation, but does not describe wujie's or micro-app's internals, so those have to be judged from their own documentation.

## Sources

- [License: MIT](https://github.com/umijs/qiankun/blob/next/LICENSE)
- [Project website](https://qiankun.umijs.org)
- [README](https://github.com/umijs/qiankun/blob/next/README.md)
- [Releases](https://github.com/umijs/qiankun/releases)
- [umijs/qiankun on GitHub](https://github.com/umijs/qiankun)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/umijs-qiankun