Micro‑Frontend Architecture with MonoRepo and Qiankun: Design, Technology Selection, and Implementation Practices

The project originally consisted of six separate PC and H5 applications, each maintained independently, leading to duplicated UI code and divergent business logic. To improve development efficiency, the team introduced a micro‑frontend approach, extracting common modules into a shared repository.

Initially, each extracted module required its own repository, which proved cumbersome. The solution was to combine all modules into a single MonoRepo and use Qiankun for runtime integration, allowing seamless switching between projects while maintaining a single source of truth.

Micro‑frontend solutions surveyed:

single‑spa – a meta‑framework that exposes render and mount hooks; flexible but requires additional work when not using a ready‑made framework.

qiankun – built on single‑spa, production‑ready, used in the team’s order module.

MicroApp – a minimal solution supporting ESM, developed by JD.

emp – leverages Webpack 5 Module Federation; works only with Webpack 5.

Garfish – framework‑agnostic with robust sandbox isolation.

npm – traditional package sharing, but increases bundle size.

iframe – limited and generally discouraged.

MonoRepo – not a micro‑frontend technique per se, but useful for sharing code across projects.

Technology selection: Because all client code uses spack , Webpack‑based micro‑frontend approaches were excluded. To minimize changes, npm and iframe methods were also rejected. The team chose MonoRepo + Qiankun to share components across projects while keeping a single repository.

Key implementation steps:

Create a packages folder at the repository root and add a pnpm-workspace.yaml file to link the packages, e.g.: packages: - "packages/*"

Ensure that the host application loads the route page before the micro‑application loads.

Register each micro‑application in the host with a wildcard path (e.g., path: '/app/*' ) and pass the active rule from the host to the child.

Install qiankun in the host and register micro‑apps using registerMicroApps and start .

Expose lifecycle hooks (bootstrap, mount, unmount) in each micro‑app and configure the bundler accordingly.

After these steps, the MonoRepo + Qiankun setup was completed, allowing independent development of each sub‑project.

Problems encountered and solutions:

Module extraction logic mismatches – ensured consistent module boundaries across projects.

Cross‑domain issues – enabled CORS in development and added appropriate headers in Nginx for production.

Login cookie sharing – used a custom fetch wrapper with CORS mode to handle authentication across domains.

CSS isolation – applied techniques such as BEM, CSS Modules, prefixes, dynamic style loading, and Web Components.

JS sandbox – relied on Qiankun’s Proxy‑based sandbox that snapshots global state before mount and restores it after unmount.

Data communication – used Qiankun’s initGlobalState for global state sharing; for simple cases, an event emitter was sufficient.

Micro‑app caching – configured Nginx to send Cache-Control: no-cache for index.html : location = /index.html { add_header Cache-Control no-cache; }

Overall, the adoption of MonoRepo and Qiankun streamlined the maintenance of multiple front‑end projects, reduced code duplication, and provided a scalable micro‑frontend architecture.