qiankun README

The project's README from github.com/umijs/qiankun. As one markdown file: README.md.

qiankun logo

npm version coverage npm downloads build status license

Documentation · Quick start · Live examples · Roadmap

English · 简体中文

qiankun（乾坤）

[!WARNING]

🚧 qiankun 3.0 is currently under active development — check out the Roadmap for details. Looking for qiankun 2.x? Its documentation lives at v2.qiankun.umijs.org.

In Chinese, qian(乾) means heaven and kun(坤) earth. qiankun is the universe.

Qiankun enables you and your teams to build next-generation and enterprise-ready web applications leveraging Micro Frontends. It is inspired by and based on single-spa.

🤔 Motivation

A quick recap about the concept of Micro Frontends:

Techniques, strategies and recipes for building a modern web app with multiple teams using different JavaScript frameworks. — Micro Frontends

Qiankun was birthed internally in our group during the time web app development by distributed teams had turned to complete chaos. We faced every problem micro frontend was conceived to solve, so naturally, it became part of our solution.

The path was never easy, we stepped on every challenge there could possibly be. Just to name a few:

After solving these common problems of micro frontends and lots of polishing and testing, we extracted the minimal viable framework of our solution, and named it qiankun, as it can contain and serve anything. Not long after, it became the cornerstone of hundreds of our web applications in production, and we decided to open-source it to save you the suffering.

TLDR: Qiankun is probably the most complete micro-frontend solution you ever met🧐.

✨ Features

Qiankun inherits the fundamentals of single-spa — independent deployment, lazy loading, and a technology-agnostic host that never dictates a micro app's stack — and adds the pieces a real product needs:

🚀 Getting started

[!NOTE]

v3 ships under the rc tag while latest still points at 2.x. Install with an explicit @rc to get it.

The fastest path is the agent skill — install it, then ask your coding agent (Claude Code, Cursor, …) to scaffold a host or a micro app wired up correctly:

npx skills add umijs/qiankun

Or add qiankun to an existing host application:

npm i qiankun@rc

Load a micro app into any container element, and keep the returned handle to unmount it:

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

If a micro app's activation is fully determined by the URL, the route-driven registerMicroApps + start APIs are the alternative orchestration model.

A micro app only has to export the three lifecycle hooks:

let root;

export async function bootstrap() {}

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

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

That is the whole contract. See the quick start for the bundler configuration each stack needs.

💿 Examples

Every example is deployed and browsable at examples.qiankunjs.com — two host shells (React and Vue) mounting the same four micro apps, each running with the JS sandbox and style isolation on, plus a standalone sandbox lab. Every app carries an "isolation lab" that demonstrates what the sandbox actually contains: globals, leaked timers, and injected styles. The shells switch between English and 简体中文, and the choice travels to the micro apps as a prop — they re-render through the update lifecycle rather than remounting.

To run them locally:

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

This builds the workspace packages and starts every app in parallel — open http://localhost:7099 for the React shell or http://localhost:7105 for the Vue one. See examples/README.md for what each app demonstrates.

📦 Packages

Package Version (click for changelogs) Description
qiankun qiankun version The framework: registerMicroApps, loadMicroApp, start, prefetch
@qiankunjs/loader loader version Streaming HTML-entry loader
@qiankunjs/sandbox sandbox version JS sandbox — usable standalone
@qiankunjs/shared shared version Asset transpilers, fetch utilities, ESM-sandbox engine
@qiankunjs/single-spa single-spa version Vendored single-spa fork the framework builds on
@qiankunjs/react react version <MicroApp /> for React
@qiankunjs/vue vue version <MicroApp /> for Vue
@qiankunjs/ui-shared ui-shared version Shared internals of the UI bindings
@qiankunjs/bundler-plugin bundler-plugin version webpack 4/5 and Vite plugins for micro apps

📖 Documentation

Full documentation lives at www.qiankunjs.com (English and 简体中文):

Design decisions are recorded as RFCs under docs/rfcs.

🎯 Roadmap

qiankun 3.0 is under active development. The plan, and the discussion around it, is in the 3.0 Roadmap.

🤝 Contributing

Ask DeepWiki

Issues and pull requests are welcome. The repository is a pnpm monorepo that requires Node ^22.15 || >=24 and pnpm@11:

pnpm install         # install every workspace package
pnpm run build       # build packages and examples
pnpm run test        # unit tests (vitest, no build needed)
pnpm run test:e2e    # end-to-end tests (Playwright, against built output)
pnpm run ci          # what CI runs: build + eslint + prettier

Commits follow Conventional Commits — releases and changelogs are derived from them, so do not hand-write changesets. AGENTS.md documents the architecture, conventions and anti-patterns in depth.

👥 Contributors

Thanks to all the contributors!

contributors

🎁 Acknowledgements

📄 License

Qiankun is MIT licensed.

qiankun (umijs/qiankun)

Searching Database…

16.7K ·GitHub
Qiankun
Что это такое?Qiankun — это JavaScript-фреймворк для создания микрофронтенд-приложений: он позволяет запускать вместе на одной странице независимо собранные и развёрнутые приложения (на React, Vue или любом другом инструменте).
Это самостоятельное приложение или фреймворк, который я добавляю в свой проект?Это фреймворк-библиотека, которую добавляют в уже существующее хост-приложение: вы загружаете отдельно собранные микроприложения в контейнерный элемент и храните ссылку на них, чтобы управлять их жизненным циклом. Самостоятельно он не работает.
Как добавить qiankun в проект?Установите npm-пакет (тег @rc — для разрабатываемой версии v3, обычный тег — для 2.x), затем вызовите loadMicroApp, чтобы смонтировать микроприложение, или используйте registerMicroApps плюс start для оркестрации на основе маршрутов. Также есть agent skill — он может сгенерировать правильно настроенное хост-приложение или микроприложение.
Нужен ли моему микроприложению определённый сборщик?Qiankun поставляется с плагинами для сборщиков webpack 4/5 и Vite, которые помечают входной скрипт и исправляют формат библиотеки на выходе — без этого микроприложение не сможет загрузиться. Само микроприложение должно лишь экспортировать три хука жизненного цикла: bootstrap, mount и unmount.
Можно ли уже сейчас пользоваться qiankun 3.0?Нет — v3 находится в активной разработке и выпускается только под тегом rc в npm, а тег latest по-прежнему указывает на старую ветку 2.x (её документация хранится отдельно на v2.qiankun.umijs.org).
Можно ли использовать qiankun с фреймворками, кроме React и Vue?Ядро загрузчика и песочница не зависят от фреймворка: микроприложению достаточно экспортировать три хука жизненного цикла. При этом qiankun отдельно предоставляет готовые компоненты-обёртки для React и Vue.
Что именно изолирует JS-песочница?Каждое микроприложение работает за Proxy-мембраной над window и document, поэтому его глобальные переменные, таймеры и обработчики событий остаются внутри приложения и автоматически очищаются при размонтировании, а не утекают на хост-страницу или в другие микроприложения.
Зачем создавать qiankun, если есть single-spa?Qiankun появился внутри компании, чтобы решить проблемы, которые single-spa оставлял открытыми: доставку ресурсов, песочницу во время выполнения, изоляцию стилей и предзагрузку. Эти возможности собраны в открытом решении, построенном поверх single-spa.
Как работает изоляция стилей без Shadow DOM?Qiankun предлагает необязательную, включаемую вручную область видимости CSS во время выполнения, построенную на нативном at-правиле CSS @scope; она охватывает и внешние таблицы стилей, поэтому не нужно переписывать CSS или платить за потери производительности, которые даёт Shadow DOM.
Можно ли использовать песочницу без остальной части микрофронтенд-фреймворка?Да — пакет @qiankunjs/sandbox публикуется отдельно и может изолировать любой сторонний скрипт даже без общего слоя оркестрации qiankun.
What are similar projects?ice, angular-webpack-starter, bit, webpack, todomvc, single-spa, mitosis, rspack
Which topics is it in?module-bundler, esm, webpack, web-framework, microservices, monorepo, sandbox, vite, vue, css, plugin, framework
Creator
umijs
Size
38.6 MB
Stars
16.7K
Updated
CommitOct 11Releasev2.10.16Nov 15
Age
7y
Commits · 90 Days