Progressive Upgrade Practice Based on Qiankun Micro-frontend Framework

This article describes a practical case study of implementing qiankun micro-frontend framework to achieve progressive upgrade of a legacy frontend project.

Project Background: The original project was started 6 years ago with Gulp+AngularJs+Bootstrap architecture, containing over 70 functional modules with continuous new requirements being developed. The old architecture could no longer meet current development demands due to: outdated technical frameworks with unmaintained dependencies; tight functional coupling with complex code logic; code redundancy with difficulties in component development and reuse; and declining development efficiency with poor developer experience.

Technical Selection: After evaluating various micro-frontend solutions (iframe, single-spa, Webpack5 Module Federation, ESM, Web Components), the team chose qiankun framework for several reasons: it is based on single-spa which provides single-spa-angularjs middleware for AngularJs projects; it implements HTML Entry via import-html-entry allowing direct use of original project HTML as sub-application entry; and it provides JS sandbox and CSS isolation that single-spa lacks.

Architecture: The application is split into main app and sub-app. The main app uses a new framework (Angular11) and registers sub-apps through qiankun. The original AngularJs project serves as a sub-app, exporting lifecycle hooks (bootstrap, mount, unmount) via single-spa-angularjs middleware. Common features like permissions, layout, and menus are implemented in the main app, while new features are also developed there. Route distribution is used: new and refactored pages use main app routes directly, while unreconstructed pages use a route prefix (/ng) to trigger sub-app mounting.

Integration Steps - Main App (Angular11): Register sub-apps and import sub-app lifecycles; obtain menu permissions and add /ng route prefix for unreconstructed pages; mount sub-apps via route prefix matching.

Integration Steps - Sub-app (AngularJs): Import single-spa-angularjs middleware and export lifecycle hooks; use window.__POWERED_BY_QIANKUN__ to detect qiankun environment, set route prefix, control menu/watermark rendering, and redirect to main app login when not authenticated.

Problem Solving:

Menu Sharing: The main app manages and renders all menus. Menu addresses are processed differently based on three scenarios: new pages in main app accessed directly; refactored pages converted via UrlMap configuration; unreconstructed pages with /subApp prefix to trigger qiankun sub-app mounting.

CSS Isolation: qiankun's CSS sandbox only ensures style isolation between sub-apps in single-instance scenarios. The team leveraged componentization to avoid global styles, with dynamic style tags mounted to document. Only the main app's Layout component could potentially pollute sub-app styles, which was controlled through CSS conventions.

Static Resource Loading: Since qiankun loads sub-app resources via fetch requiring full domain addresses with CORS support, and modifying the original Gulp-built AngularJs project would be extensive, the team used proxy configuration in both development and production environments.

Project Value: The solution provides incremental upgrade capability for quick adoption of new frameworks; progressive upgrade allowing flexible refactoring of frequently iterated modules based on product needs; low risk through partial feature releases; and low intrusion allowing the original project to run, develop, and deploy independently.

Generalizability: The approach addresses common challenges in large frontend project refactoring. Micro-frontend's cross-technology-stack nature suits refactoring projects with various tech stacks. The implemented methods for navigation sharing, permission management, resource loading, and CSS/JS isolation can be reused in other projects. The main app can use Vue, React, Angular, while the original project can be Vue/React/Angular/AngularJs/jQuery.