Guide · Open source

How to use qiankun: install, load micro apps and run examples

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

qiankun is an open-source JavaScript library that lets one host web page load and run several independent web apps, possibly built with different frameworks and deployed by different teams. It is based on single-spa and adds HTML-entry loading, a JS sandbox and optional style isolation. This guide shows you how to install it, load a micro app into a container element, write the lifecycle hooks a micro app needs and run the bundled examples.

qiankunumijs/qiankun · ★ 16.7k · MIT Install options & downloads

Quick start

1Check your fit. Confirm you have several teams or frameworks that need to share one page, since small single-team sites add unnecessary complexity.
2Install the rc build. Run npm i qiankun@rc in your host application, because v3 is published under the rc tag.
3Load a micro app. Call loadMicroApp with a name, entry URL and container element, and keep the returned handle.
4Export lifecycle hooks. In each micro app, export bootstrap, mount and unmount, with mount rendering into props.container.
5Run the examples. Clone the repository, run pnpm install and pnpm start:example to see the React and Vue shells.

What qiankun is and when to use it

qiankun is a micro frontend framework. A host page loads separate micro apps, and each micro app can use its own stack. The project describes its core features as HTML entry, a JS sandbox that keeps each app's globals and listeners contained, native ESM support, opt-in style isolation, prefetching and UI bindings for React and Vue.

Teams splitting one large web app across several groups that deploy independently
Projects that mix frameworks such as React and Vue on the same page
Developers who already use single-spa and want extra sandboxing and loading features
Hosts that need to load micro apps lazily into a container element

Check whether qiankun fits your project

The setup adds complexity that a single app does not need, so small single-team sites are a poor fit. The README notes that the 3.0 features are still under development and are installed via the rc tag, so teams that need the stable 2.x line today should check the 2.x documentation instead. If you only need a sandbox for third-party scripts, the separately published @qiankunjs/sandbox package is the better choice.

Install qiankun in a host application

Add qiankun to an existing host application with your package manager. The README uses the rc tag because v3 ships under it while latest still points at 2.x, so install with an explicit @rc.

Prerequisites for the examples: Node.js and pnpm

npm i qiankun@rc

Load a micro app into a container

Call loadMicroApp with a name, an entry URL and a container element. Keep the returned handle so you can unmount the micro app when that part of the page goes away.

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();

Write the lifecycle hooks in a micro app

A micro app only has to export three lifecycle hooks: bootstrap, mount and unmount. mount receives props that include the container element, and unmount cleans up what mount created. The README describes this as the whole contract, and points to the quick start for the bundler configuration each stack needs.

bootstrap runs once before the first mount
mount renders the app into props.container
unmount tears the app down

let root;

export async function bootstrap() {}

export async function mount(props: { container: HTMLElement }) {
  root = render(props.container);
}

export async function unmount() {
  root.unmount();
}

Run the bundled examples locally

Clone the repository and install workspace dependencies with pnpm, then start all example apps in parallel. The examples include two host shells, React and Vue, mounting the same four micro apps. According to the README, the local start builds the workspace packages first, and the React shell is served on port 7099 while the Vue shell is on port 7105.

Live examples are deployed at examples.qiankunjs.com

git clone https://github.com/umijs/qiankun.git
cd qiankun
pnpm install
pnpm start:example

What people use it for

Splitting a large site so separate teams can deploy their sections independently
Hosting a React micro app and a Vue micro app on the same page
Lazily loading a micro app into a container when a user reaches that part of the site
Adding sandboxing to an existing single-spa setup

Frequently asked questions

Is qiankun free to use?

qiankun is published under the MIT licence, according to the repository. The README lists the licence badge and the project's MIT licence file, so you can use it in commercial projects under those terms.

How do I install qiankun?

Run npm i qiankun@rc in your existing host application. The rc tag is needed because v3 is published under it while latest still points at 2.x.

What do I need to run qiankun?

The README lists Node.js and pnpm as prerequisites, and pnpm is only needed to run the examples locally. Your host and micro apps need to export the lifecycle hooks described in the guide.

Is qiankun better than single-spa?

qiankun is based on single-spa and adds HTML-entry loading, a JS sandbox, style isolation, prefetching and UI bindings. If you only need routing-based orchestration without those features, single-spa on its own may be enough.

Should I use qiankun or the standalone sandbox?

Use qiankun for composing full micro apps into one page. If you only need to contain third-party scripts, the separately published @qiankunjs/sandbox package is built for that job without a micro frontend framework.

Why does my micro app not load?

Check that the entry URL in loadMicroApp points to a running micro app and that the micro app exports bootstrap, mount and unmount. The README's quick start covers the bundler configuration each stack needs.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

qiankun suits teams that split one large web app across several groups or frameworks and want sandboxing and lazy loading on top of single-spa. Small single-team sites, or teams that need only a standalone sandbox or the stable 2.x line today, should pick something simpler or a different option such as the separate sandbox package.

Install options & downloads