Introduction, Architecture, and Practical Usage of the qiankun Micro‑Frontend Framework
This article provides a comprehensive overview of the qiankun micro‑frontend framework—including its background, core concepts of micro‑frontends, comparison with other solutions, detailed configuration examples for host and child applications, implementation details such as sandbox mechanisms, common pitfalls, and the overall impact on development efficiency and project complexity.
The qiankun framework, originated from Ant Financial, is a micro‑frontend solution built on top of single‑spa that enables developers to split a large application into independent sub‑applications without being constrained by technology stacks, allowing gradual migration of legacy projects.
Background : Large monolithic applications become difficult to maintain as requirements evolve; micro‑frontend architecture addresses this by decomposing the UI layer similar to micro‑services.
Micro‑frontend Overview : First proposed by ThoughtWorks in 2016, it aggregates multiple small front‑end apps into a single user experience while preserving independent development, testing, and deployment.
Common Frameworks : The ecosystem includes single‑spa (core routing and lifecycle), qiankun (adds sandbox, UMI features, pre‑load, etc.), Icestark (React‑friendly), and Mooa (Angular‑focused). All are built on single‑spa ’s lifecycle (bootstrap, mount, unmount, unload).
qiankun Usage – Host Application Configuration :
// Install qiankun
$ yarn add qiankun # or npm i qiankun -S
// main.js of host app
import Vue from 'vue'
import App from './App.vue'
import { registerMicroApps, start, setDefaultMountApp, runAfterFirstMounted } from 'qiankun'
new Vue({ render: h => h(App) }).$mount('#main-app')
const apps = [
{ name: 'vueApp', entry: '//localhost:8085', container: '#vue', activeRule: '/vue', props: { a: 1 } },
{ name: 'reactApp', entry: '//localhost:3000', container: '#react', activeRule: '/react' }
]
registerMicroApps(apps)
start({ prefetch: false, strictStyleIsolation: true })
setDefaultMountApp('/vue')
runAfterFirstMounted(() => { console.log(999) })Child Application Configuration (Vue example) :
// index.html
<!DOCTYPE html>
<html lang="">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width,initial-scale=1.0">
<title>Vue App</title>
</head>
<body>
<noscript>JavaScript is required.</noscript>
<div id="main-app"></div>
</body>
</html>
// App.vue
<template>
<div id="vueApp"><Home/></div>
</template>
<script>
import Home from './views/Home.vue'
export default { name: 'App', components: { Home } }
</script>
// router.js
import Vue from 'vue'
import VueRouter from 'vue-router'
import Home from '../views/Home.vue'
Vue.use(VueRouter)
export default new VueRouter({ mode: 'history', base: '/vue', routes: [{ path: '/home', name: 'Home', component: Home }] })Implementation Principles : qiankun combines single‑spa (application scheduling) with import‑html‑entry (fetch‑based loading of HTML/JS assets). It registers micro‑apps via registerApplication, determines activation through URL matching, and executes the full lifecycle.
Sandbox Mechanisms : To avoid global pollution, qiankun provides three sandbox types— SnapshotSandbox (for browsers without Proxy), SingularProxySandbox (single‑instance Proxy), and ProxySandbox (multiple apps). They capture and restore global state before/after mount, isolate CSS via ShadowDOM or scoped CSS, and manage JS isolation.
export default class SnapshotSandbox implements SandBox {
proxy: WindowProxy
name: string
type: SandBoxType
sandboxRunning = true
private windowSnapshot!: Window
private modifyPropsMap: Record<any, any> = {}
constructor(name: string) { this.name = name; this.proxy = window; this.type = SandBoxType.Snapshot }
active() { /* record snapshot and restore changes */ }
inactive() { /* revert to snapshot */ }
}Common Issues and Mitigations : Problems include shared localStorage keys, style leakage, same‑origin dead loops, and version conflicts between host and child frameworks. Recommendations cover careful resource sharing, explicit CSS isolation, and coordinated version management.
Impact of Adopting qiankun : Improves maintenance efficiency by enabling incremental upgrades, but increases overall project complexity due to added orchestration, testing overhead, and the need for clear team responsibilities.
Conclusion : Micro‑frontend architecture solves the pain points of monolithic front‑ends, yet introduces new challenges; adoption should be weighed against project goals, resources, and the ability to manage the added complexity.
Signed-in readers can open the original source through BestHub's protected redirect.
This article has been distilled and summarized from source material, then republished for learning and reference. If you believe it infringes your rights, please contactand we will review it promptly.
Xueersi Online School Tech Team
The Xueersi Online School Tech Team, dedicated to innovating and promoting internet education technology.
How this landed with the community
Was this worth your time?
0 Comments
Thoughtful readers leave field notes, pushback, and hard-won operational detail here.