Why Sub‑Application Routes Do Not Update When the Main Application Switches Routes in Qiankun and How to Fix It

This article is originally published on the Rare Earth Juejin Tech Community and may not be reproduced within 14 days without permission; after 14 days, reproduction without authorization is prohibited.

Preface

Hello, I am Haiguai. Today I want to share a problem I encountered when using Qiankun: the sub‑application route does not change when the main application switches routes.

The code for this article is placed in the qiankun-bigass-app repository on the routes branch.

Project Background

We have several projects, some small management back‑ends (green) and a larger, more generic management back‑end (red). We aim to use Qiankun's micro‑frontend capabilities to manage these projects by treating the red project as the main app and the green projects as sub‑apps, gradually integrating important features into the main platform.

Only selected important features are integrated into the main platform, while the remaining functionalities stay within their respective projects.

The desired page layout looks like this:

Problem Discovery

We expect each Tab in the main app's sidebar to correspond to a route that loads the appropriate sub‑app and its page. For example:

Click "User Info" → main app route changes to /userMicroApp/userinfo and loads UserMicroApp .

UserMicroApp detects the sub‑route /userinfo and switches to the "User Info" page.

When we try to switch between "History" and "Room Info", we only need to add more routes in the main app. A simplified example uses "Taobao Home" and "About" pages.

<HashRouter>
  <div class="app">
    <div class="sidebar">
      <h1>LOGO</h1>
      <ul>
        <li><Link to='/taobao/home'>淘宝首页</Link></li>
        <li><Link to='/taobao/about'>淘宝关于</Link></li>
      </ul>
    </div>
    <Routes>
      <Route path="/taobao/home" element={null} />
      <Route path="/taobao/about" element={null} />
    </Routes>
    {/* sub‑app mount point */}
    <div id="subapp-viewport" />
  </div>
</HashRouter>

The main app registers sub‑apps as follows:

registerMicroApps([
  {
    name: 'taobao',
    entry: '//localhost:7101',
    container: '#subapp-viewport',
    loader: (loading) => setLoading(loading),
    activeRule: '/#/taobao'
  }
]);
start();

In the sub‑app we also configure /home and /about routes:

<Router basename={window.__POWERED_BY_QIANKUN__ ? '/taobao' : '/'}>
  <nav>
    <Link to="/">Home</Link>
    <Link to="/about">About</Link>
  </nav>
  <Suspense fallback={null}>
    <Switch>
      <Route path="/home" exact component={Home} />
      <Route path="/about" component={About} />
    </Switch>
  </Suspense>
</Router>

We notice that clicking the main app's <Link> does nothing, while clicking the <Link> inside the sub‑app works. This is the core issue: the main app changes route but the sub‑app does not receive the change.

Analysis of the Cause

The routing change flow is:

Main app clicks <Link>

Event is triggered

Main app captures the route change

Main app loads the sub‑app

Sub‑app captures the route change

Sub‑app switches page

In practice, the main app can switch its own pages, but the sub‑app never receives a hashchange event because the router uses history.pushState , which does not fire hashchange . Only changes to window.location.hash trigger that event.

Therefore, the sub‑app cannot detect the route change and its page remains static.

Routing Implementation Principle

Both Vue Router and React Router support Hash and History modes. In Hash mode they try history.pushState first and fall back to modifying window.location.hash . The push function in React Router ultimately calls globalHistory.pushState , which does not emit hashchange . Consequently, sub‑apps miss the event.

Solution

To make the sub‑app react to the main app's navigation, we need to ensure a hashchange event is dispatched. Two approaches:

Manually Dispatch the Event

history.push('/about')
const event = new Event('hashchange')
window.dispatchEvent(event)

Replace <Link> with <a>

Using a plain anchor tag forces a hash change:

<ul>
  <li><a href='/#/taobao/home'>淘宝首页</a></li>
  <li><a href='/#/taobao/about'>淘宝关于</a></li>
</ul>

Summary

The root cause of "sub‑application route does not update when main application switches routes" is that the sub‑app does not receive the hashchange event. The problem can be solved either by manually dispatching a hashchange event after navigation or by using plain <a> tags instead of router <Link> components.