In the context of admin panels, micro frontends are rarely pursued for the sake of conceptual novelty but rather to solve real organizational and legacy debt issues.

This article is based on the evolutionary process of a real admin panel project, discussing how this architecture evolved step by step from an old monolithic system, how the main shell and child applications collaborate, and the pitfalls encountered along the way.

Why This Refactoring?

Before the refactoring, the company had two independent admin systems running in parallel:

One was the backend of the old official website, using WordPress + PHP, with core business pages embedded using Vue2.
The other was a cloud service admin panel written purely in Vue2.

As the business became more complex and the official website was being refactored, the old website and its admin panel were gradually deprecated. However, the cloud service admin panel carried core business and could not be directly overhauled. At the same time, the team needed to develop new businesses like Blog, ERP, Chat, and Support Log Center in parallel.

If we continued with a monolithic approach, either the new business would be dragged down by the old system, or we would face a huge risk of a full-scale refactoring. Our goals at that time were very practical:

Do not affect core business: The old cloud service admin panel would not be refactored for now; by modifying build and route configurations, it would be directly integrated into the new system "with its existing issues."
Decouple new business: New businesses would be developed and deployed independently as child applications, with teams not interfering with each other.
Unify user experience: Users would enter from a single entry point, with unified navigation, permissions, and visuals.

The resulting structure was very clear:

Layer	Responsibility	Status
Main Shell Layer	Unified layout, menu rendering, permission checks, runtime coordination	Integrated under unified rules
Old System Layer	Hosts the existing cloud service admin business	Modified configuration, adapted as a child application
New Child App Layer	Hosts new business domains like Blog, ERP, Chat	Fully autonomous, independent evolution

A diagram can quickly illustrate the three-layer relationship:

The Core Role of the Main Shell: Runtime Orchestrator

In this architecture, the main shell is not responsible for any specific business logic; its sole identity is that of a Runtime Orchestrator.

It handles system-level concerns:

Does the user have permission to access this page?
Which child application should be mounted based on the current URL?
When switching between child applications, how to synchronize the sidebar selection state and header breadcrumbs?

To ensure the stability of the main shell, the entire startup chain is strictly controlled to be initialized in order:

This order cannot be disrupted because the output of each step is the input to the next:

Without session and profile, subsequent APIs cannot obtain identity.
Without permission, permission sets are unavailable.
Next, configurations are fetched; without them, the main shell does not even know which child application to load or which menu to render.

Dynamic Assembly and Module Singleton

To avoid frequent releases of the main shell alongside business changes, we completely extracted configuration files like childApps.json and pages.json from the codebase. These configurations are hosted in a Git repository, managed and dynamically distributed via a configuration center. Adding a new child application or changing a menu name no longer requires rebuilding the main shell – only the configuration needs to be updated.

At the same time, internal modules of the main shell such as ChildApps, Pages, Settings, and AppStateController were all designed as singleton classes. They maintain private states internally and expose limited APIs. This effectively prevents global state from being read/written disorderly by components, hooks, or utility functions in a micro frontend environment.

How Are Child Applications Integrated?

The integration process for child applications consists of three progressive stages: Registration, Routing, and Mounting.

1. Configuration Registration

In the configuration center, each child application must define its boundaries clearly:

{
  "child-app-blog-admincp": {
    "url": "/child-app-blog-admincp/",
    "name": "child-app-blog-admincp",
    "keepAlive": true,
    "inline": true,
    "disableSandbox": false,
    "entry": "index.html",
    "index": "article/"
  }
}

2. Route Routing

The main shell does not hardcode dynamic routes to each child application's pages; instead, it uses wildcard routing, delegating fine-grained routing within the child application back to itself:

<Route
  path={item.url + '*'}
  element={<CompChildAppSite {...item} />}
/>

3. Runtime Mounting

We use @micro-zoe/micro-app for loading child applications and sandbox isolation. The main shell takes over runtime contracts through lifecycle hooks of the container:

onBeforemount: Injects shared state (Token, user info) into the child application.
onMounted: Synchronizes header state, records mount time.
onDataChange: Listens to data reported by the child application (e.g., internal route change, notifying the main shell to update the URL).
onUnmount: Destroys listeners and performs garbage collection.

Evolution and Compromise in Technology Selection

In early designs, we attempted an appealing combination: using micro-app for child application mounting and runtime sandbox, and Module Federation (via Vite plugin vite-plugin-federation) to expose shared modules (e.g., HTTP client, common components, type definitions) from the main shell to child applications.

However, during actual iterations, we encountered severe contract and version governance issues.

When the main shell's capabilities exposed via Module Federation underwent API changes or underlying third-party library upgrades, due to runtime consumption, if the child application was not adapted synchronously, it would cause errors in production. The runtime chain of micro frontends is too long, leading to exponentially increased uncertainty from such dynamic consumption.

Moving from Module Federation to npm Packages

To address this pain point of version conflicts, we made a pragmatic adjustment: we completely extracted the shared base capabilities, state interfaces, and common components of the main shell and encapsulated them into an independent private npm package.

In the development of new business admin panels, child applications no longer consume the main shell's modules at runtime; instead, they use the shared capabilities by installing this npm package at compile time.

Benefits: The child application locks the version of the npm package. When the main shell upgrades capabilities, the child application can choose not to follow, or upgrade after local testing, locking the risk at compile time.
Cost: The flexibility of dynamic updates via Module Federation is lost. If an urgent bug fix is needed, all child applications must be rebuilt and released. However, compared to uncontrollable runtime crashes in production, this cost is fully acceptable in team collaboration.

Pitfalls and Costs

If your system scale hasn't reached a certain level, it is not recommended to try micro frontends lightly. While solving organizational and legacy issues, this architecture brings high hidden costs:

Harsh local development environment: Due to issues like main shell fetching child application static resources, cross-origin APIs, dynamic route proxying, local development usually requires complex domain mapping (Hosts) and local certificates.
High contract maintenance cost: Route prefixes, namespaces, event protocols, private fields of AppState must remain highly consistent. Once someone fails to follow the convention (e.g., the child app changes the base route without notifying), the troubleshooting chain becomes extremely painful.
Debugging difficulty doubles: When a bug is reported, it could originate from frontend configuration, Git repository configuration, main shell lifecycle, shared package version, or the child application's own logic. The troubleshooting cost is significantly higher than traditional monolithic systems.

Conclusion

From the old WordPress+Vue2 hybrid system, to the cloud service admin panel forcibly integrated with modified configuration, to the fully npm-modularized new business – in this project, micro frontends are essentially a means to manage organizational complexity and accommodate legacy debts, not for showing off technique.

Before undertaking technical transformation, it is more important to think through system boundaries, page models, and permission consolidation, rather than blindly pursuing framework selection.

0 Comments

Leave a Comment