Micro‑Frontend Architecture with Qiankun: Practical Implementation and Migration Strategies

Enterprise back‑office systems (CMS, asset management, finance, etc.) often become monolithic "big‑stone" applications as teams and business complexity grow. To avoid unmanageable code bases and improve development efficiency, a progressive migration to a micro‑frontend architecture is proposed.

The core value of micro‑frontends is technology‑stack independence: each sub‑application can be developed and deployed separately, allowing Vue, React, Angular, or legacy JQuery apps to coexist while new features are built with a unified stack.

Micro‑frontend concepts were introduced in 2016, borrowing ideas from micro‑services. The architecture splits a large UI into independent sub‑apps that can be assembled like building blocks, reducing coupling and improving maintainability.

Several micro‑frontend frameworks exist (single‑spa, Qiankun, MicroApp, Wujie). After a brief comparison, Qiankun was chosen for its proven stability (2000+ production apps at Ant Group), community adoption, and seamless integration with the Umi scaffold used in the organization.

export const MicroAppConfig: MicroAppConfigType = { [MicroAppNameEnum.App1]: { name: MicroAppNameEnum.App1, appName: 'xx系统', entry: getMicroAppEntry(MicroAppNameEnum.App1), container: '#MicroAppContainer_App1', prefixPath: '/app1', // ...other config }, [MicroAppNameEnum.App2]: { ... }, [MicroAppNameEnum.App3]: { ... }, };

The main app aggregates menus from all sub‑apps via a single configuration file, prefixes each sub‑app’s routes to avoid conflicts, and maintains a whitelist ( MasterAppPathPrefixList ) for routes that should be handled directly by the host.

export const MasterAppPathPrefixList = [ '/router-1', '/router-2', '/router-3/page-1', ];

To enable multiple sub‑apps to be active simultaneously, the Qiankun loadMicroApp API is used. The host listens to route changes, loads the corresponding micro‑app into a dedicated container, and keeps already loaded apps alive.

const handleMenuSelect = useCallback((path: string) => { if (microApp) { const newState = { ...loadedApps }; const childRoutePath = path.replace(microApp.prefixPath || '', ''); setActiveAppName(microApp.name); if (!loadedApps[microApp.name]) { const app = loadMicroApp(microApp); newState[microApp.name] = { app, childRoute: [] }; } newState[microApp.name].childRoute.push(childRoutePath); setLoadedApps(newState); } else { setActiveAppName(''); } }, [loadedApps, microApp]);

Sub‑app Keep‑Alive is achieved using Vue’s built‑in keep-alive component and React’s react-activation library, preserving page state when users switch tabs.

<keep-alive :include="cachedViews"> <router-view :key="$route.fullPath"></router-view> </keep-alive>

import { KeepAlive } from 'react-activation'; <KeepAlive name={path} id={path} saveScrollPosition="screen"> {children} </KeepAlive>

Common SDKs (e.g., analytics, SSO) are loaded only in the host app and guarded in sub‑apps by checking the global variable __POWERED_BY_QIANKUN__ to avoid duplicate execution.

Style isolation is handled by enabling Qiankun’s sandbox and, when needed, adding manual scopes (e.g., Ant Design’s ConfigProvider ) or experimental runtime isolation:

// original CSS .app-main { font-size: 14px; } // rewritten by Qiankun div[data-qiankun-finance] .app-main { font-size: 14px; }

Cross‑application navigation is implemented either via native history.pushState() or by passing the host’s router instance to sub‑apps.

The migration resulted in over 90% of legacy code being integrated into the micro‑frontend platform, with a unified React stack for new features, higher component reuse, and improved ROI.