wujie

Wujie micro-frontend

Compatible with wujie >= 2.1.0. For detailed APIs and troubleshooting, see references/。

Framework overview

Wujie uses same-origin iframe to run sub-application JS (a natural window sandbox), and uses WebComponent（shadow DOM） to render sub-application DOM (natural CSS isolation). The sub-application router runs independently inside the iframe, and synchronizes with the main application URL by hijacking history and the main application URL.

Comparison:

• iframe approach: perfect isolation but lost routing, restricted popups, difficult communication
• qiankun: requires router modification, cannot activate multiple applications simultaneously, poor Vite ESM support
• Wujie: component-based integration, multiple applications online simultaneously, almost zero sub-application modification

Package selection

Main application tech stack	npm package	Component name
No framework / any	wujie	Call APIs directly
Vue 2	wujie-vue2	<WujieVue>
Vue 3	wujie-vue3	<WujieVue>
React	wujie-react	<WujieReact>

Sub-applicationNot requiredInstall the wujie package, access the injected object via window.$wujie .

Integration decision

用户问题
  ├─ 选包 / 组件怎么用？        → references/main-app.md
  ├─ API 参数 / $wujie？        → references/api.md
  ├─ 子应用要不要改？怎么改？    → references/sub-app.md
  ├─ 路由 / 菜单 / 跳转 / 多Tab → references/routing.md
  ├─ 保活 / sync / 预加载 / 性能 → references/modes.md
  ├─ props / bus 通信？         → references/communication.md
  ├─ 插件 / 生命周期？          → references/plugin-lifecycle.md
  ├─ 部署 / 发版 / 404？        → references/deployment.md
  └─ 报错 / 组件异常？          → references/faq.md（先查索引）

Minimal integration (Vue3 main application)

npm i wujie-vue3

// main.js
import { createApp } from "vue";
import WujieVue from "wujie-vue3";

const app = createApp(App);
app.use(WujieVue);
app.mount("#app");

<!-- 页面组件 -->
<template>
  <WujieVue name="vue3" url="//localhost:7300/" width="100%" height="100%" :sync="true" />
</template>

When the sub-application satisfies cross-origin (CORS), usuallyzero modificationis enough to run. A Vite sub-application needs to change window.location to $wujie.location。

Three run modes (quick reference)

Mode	Condition	Can changing the url navigate routes	Sub-application modification
Rebuild	Default	Yes (when sync is limited by URL synchronization parameters)	Not required
Keep-alive	alive: true	No, requires bus communication	Not required
Singleton	alive: false + lifecycle modification	Yes	Requires __WUJIE_MOUNT

See references/modes.md。

Recommended integration process

- [ ] 确认主应用框架 → 选 npm 包
- [ ] 子应用配置 CORS（跨域 + cookie 场景加自定义 fetch）
- [ ] 确定运行模式：重建 / 保活 / 单例
- [ ] 是否需要路由同步 sync、预加载 preloadApp
- [ ] 设计主应用路由结构（见 routing.md）
- [ ] 确定通信方式：props / bus / window.parent
- [ ] 按需读取 references，不猜测 API 参数
- [ ] 代码对照 examples 官方 demo 写法

Reference index

File	When to read
api.md	Check setupApp/startApp/preloadApp parameters, bus, $wujie
main-app.md	Vue2/Vue3/React component Props, setupApp coordination
sub-app.md	Sub-application CORS, lifecycle modification, Vite special handling
routing.md	Main application menu navigation, keep-alive routes, multiple tabs, deep link
modes.md	alive/sync/degrade/fiber, preloading strategy, performance optimization
communication.md	Three communication methods: props/bus/window
plugin-lifecycle.md	Plugin configuration, lifecycle hooks, attrs empty page
deployment.md	nginx caching, release 404, custom fetch
faq.md	Error troubleshooting index (CORS, popup layer misalignment, rich text, etc.)

AI work constraints

1. In keep-alive mode, it is forbidden to suggest changing url to navigate sub-application routes, bus communication must be used (see routing.md)
2. Vite sub-applicationin window.location gets the main application address, must use $wujie.location
3. name Must be globally unique; multiple Tabs with the same name will conflict (see the multi-tab section in routing.md)
4. Before giving a solution, confirm whether the sub-application is rebuild/keep-alive/singleton, as the routing behavior differs among the three
5. For troubleshooting, first check the faq.md index, then dig into the corresponding reference