Mastering Micro‑Frontend Architecture with icestark: From Scenarios to Isolation

Scenario Analysis

Micro‑frontend was first mentioned on ThoughtWorks’ 2016 radar, and teams have since tried to split or combine monolithic web apps along various dimensions. Two scenarios demand strong micro‑frontend solutions: workbench‑type products that need consistent cross‑system operations, and large monolithic applications that suffer from growing bundle size, slower builds, and increasing development and collaboration costs.

Workbench Scenario

From a product perspective, users want seamless cross‑system actions and a unified experience. Technically, independent systems lack unified control, leading to duplicated capabilities.

Large Monolithic Application

As business requirements evolve, the application’s complexity and bundle size increase, slowing build times and degrading debugging experience. Incremental architectural upgrades become difficult, and adding new features or integrating other capabilities strains the SPA architecture.

Technical Selection

Beyond micro‑frontend, other architectural options exist.

SPA/MPA

SPA/MPA provides a cohesive system experience and manageable technical complexity for simple applications, but as the app grows, it faces the same scalability and maintainability challenges that micro‑frontend aims to solve.

iframe

Iframe was a common solution before micro‑frontend, handling third‑party integrations well, but it introduces user‑experience issues such as double scrollbars, unsynchronized routing, and overlay conflicts.

Shared Framework Components

Packaging common UI logic as npm components enables reuse across systems, yet it does not address continuous architectural upgrades or cross‑system user‑experience optimization.

Micro‑Frontend

Micro‑frontend balances technical complexity and user experience, allowing independent development and deployment of functional modules that are later integrated into a single system.

Micro‑Frontend Architecture

icestark abstracts the technical details of micro‑frontend integration. The framework app handles layout, routing, and registration, while micro‑apps are independent SPA applications containing one or more pages.

Core Concepts

icestark defines two core concepts: the framework app and the micro‑app.

The framework app manages overall layout, registers micro‑apps, and provides common UI such as Header and Sidebar. Registration includes the micro‑app’s resource URL and base route.

A micro‑app is a business‑oriented SPA that may contain multiple pages or routes.

Micro‑App Registration

The framework app uses icestark’s AppRouter component to mount micro‑apps.

<AppRouter>
  <AppRoute
    path={['/', '/message', '/about']}
    title="Common Page"
    url={['//unpkg.com/icestark-child-common/build/js/index.js', '//unpkg.com/icestark-child-common/build/css/index.css']}
  />
  <AppRoute
    path={['/', '/message', '/about']}
    title="Common Page"
    entry="https://ice.alicdn.com/icestark/child-common-angular/index.html"
  />
</AppRouter>

In the configuration, path defines the base route, url points to the bundle resources, and entry can load an entire HTML page, bypassing manual JS/CSS handling.

Workflow Changes

After adopting micro‑frontend, two workflows change:

Micro‑app development becomes independent with its own repository, CI/CD pipeline, and build artifacts that are registered in the framework app.

The framework app maintains registration info, matches incoming routes to the appropriate micro‑app, loads its resources, and renders it. Cross‑app navigation triggers route matching again.

Routing Rules

icestark’s routing mirrors React‑Router concepts such as path and exact. Example registrations:

Visiting /seller matches the first registration.

Visiting /data or /message matches the second.

Visiting /seller/a matches the third.

Only when the route exactly matches /seller (with exact set) does the first registration apply.

Fallback Route

A micro‑app registered with / acts as a fallback, rendering pages such as login, 404, or logout when no other route matches.

Route Hijacking

icestark intercepts two types of routing events to react to navigation changes: popstate and hashchange from the History API. pushState and replaceState on window, which fire during forward/back navigation.

During initialization, AppRouter installs these hijacks; they are removed when the router unmounts.

Route hijacking occurs during the micro‑frontend configuration initialization phase, i.e., when AppRouter mounts.

Application Communication

icestark provides a lightweight event‑bus via @ice/stark-data, using window as a bridge so that both framework and micro‑apps can publish and listen to events without tight coupling.

Micro‑Frontend Isolation

icestark follows two isolation principles: prioritize developer experience over strict isolation, and focus on B‑side (internal) scenarios rather than uncontrolled third‑party integrations.

Developer experience is paramount; a perfect isolation that adds heavy overhead is unacceptable.

Most micro‑frontend use cases involve internal systems, where security and control are manageable.

Isolation covers both CSS and JS.

Style Isolation

Two approaches are recommended:

Use CSS Modules in each micro‑app to generate hashed class names, ensuring natural isolation.

Apply a CSS prefix or namespace to shared component libraries, separating framework and micro‑app styles.

Shadow DOM Approach

Shadow DOM is not used currently because it requires additional adaptation, especially for third‑party component libraries, event delegation in React, and assets like fonts or SVGs.

Dialog components may escape the shadow root, losing styles.

React’s delegated events are attached to document, which can be blocked by shadow boundaries.

Assets such as @font-face and SVGs may not render correctly.

icestark continues to explore a more out‑of‑the‑box Shadow DOM solution.

Script Isolation

icestark employs a proxy‑based sandbox that wraps micro‑app code with with and new Function, intercepting window accesses via Proxy. It snapshots global variable changes and restores them when the micro‑app is unmounted, also handling setTimeout and setInterval cleanup.

Third‑Party Isolation

For untrusted third‑party content, iframe remains the safest isolation method. icestark can define a base route and render the iframe via a custom render function.

Micro‑Module Capability

Micro‑modules complement micro‑frontend by providing reusable, route‑agnostic units that can be dynamically composed on a page.

They solve module coexistence, enabling multi‑tab scenarios without coupling to routing.

They support dynamic composition of forms, lists, and other widgets for flexible page construction.

Micro‑Module Architecture

Micro‑modules are packaged as UMD bundles (or npm packages) exposing mount and unmount lifecycles. They do not manage routing, keeping integration simple.

Micro‑Module Mounting

Modules are rendered via the MicroModule component:

import { MicroModule } from '@ice/stark-module';

const App = () => {
  const moduleInfo = {
    name: 'moduleName',
    url: 'https://localhost/module.js',
  };
  return <MicroModule moduleInfo={moduleInfo} />;
};

The surrounding business logic decides when and where to display each module.

Conclusion

Micro‑frontend architecture, exemplified by icestark, offers a scalable solution for large monolithic and workbench scenarios, improving system maintainability and developer experience. Combined with micro‑modules, it expands the possibilities for fine‑grained, dynamic front‑end composition.

For more details, see the icestark repository at https://github.com/ice-lab/icestark and the ICE framework at https://github.com/alibaba/ice .