JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 2
  • Score
    100M100P100Q68184F
  • License MIT

一个轻量级的微前端框架

Package Exports

  • @jserxiao/xmicro
  • @jserxiao/xmicro/dist/index.esm.js
  • @jserxiao/xmicro/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@jserxiao/xmicro) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@jserxiao/xmicro

一个轻量级、渐进式的微前端框架，支持多框架集成、沙箱隔离、ES模块应用等特性。

✨ 特性

  • 🚀 轻量级 - 核心代码 gzip 后仅 ~15KB，无第三方依赖
  • 🔒 沙箱隔离 - Proxy 沙箱 + 快照沙箱降级方案
  • 📦 HTML Entry - 支持 HTML Entry 方式加载子应用
  • ⚡ ES 模块支持 - 原生支持 Vite、Snowpack 等现代构建工具
  • 🔄 生命周期管理 - 完整的应用生命周期钩子
  • 📡 通信机制 - Props 传递 + 事件总线
  • 🎨 CSS 隔离 - 命名空间 + Shadow DOM 可选
  • 🔗 路由隔离 - 自动注入基础路由信息
  • 🎯 TypeScript 支持 - 完整的类型定义

📦 安装

# npm
npm install @jserxiao/xmicro

# yarn
yarn add @jserxiao/xmicro

# pnpm
pnpm add @jserxiao/xmicro

🚀 快速开始

主应用配置

import xMicro from '@jserxiao/xmicro';

// 注册子应用
xMicro.registerApps([
  {
    name: 'vue-app',
    entry: 'http://localhost:8081',
    activeRule: '/vue',
    container: '#subapp-container',
    props: {
      // 传递给子应用的参数
      token: 'xxx',
      user: { name: 'test' }
    }
  },
  {
    name: 'react-app',
    entry: 'http://localhost:8082',
    activeRule: '/react',
    container: '#subapp-container'
  }
]);

// 启动框架
xMicro.start();

子应用配置

方式一：导出生命周期钩子（推荐）

// Vue 3 示例
let app = null;

async function bootstrap() {
  console.log('Vue app bootstrap');
}

async function mount(props) {
  console.log('Vue app mount', props);
  app = createApp(App);
  app.use(router);
  app.use(store);
  app.mount(props.container ? props.container.querySelector('#app') : '#app');
}

async function unmount() {
  console.log('Vue app unmount');
  if (app) {
    app.unmount();
    app = null;
  }
}

// 导出到全局
window.__MICRO_APP_EXPORTS__ = { bootstrap, mount, unmount };
// React 示例
let root = null;

async function mount(props) {
  const container = props.container 
    ? props.container.querySelector('#app') 
    : document.getElementById('app');
  root = ReactDOM.createRoot(container);
  root.render(<App />);
}

async function unmount() {
  if (root) {
    root.unmount();
    root = null;
  }
}

window.__MICRO_APP_EXPORTS__ = { mount, unmount };

方式二：无感知接入（ES 模块应用）

对于 ES 模块应用（如 Vite 项目），框架会自动处理，无需修改子应用代码。

但建议在子应用中检测微前端环境，以适配路由：

// Vite + Vue 项目示例
import { createRouter, createWebHistory } from 'vue-router';

// 获取微前端注入的基础路由
const baseRoute = window.__XMICRO_BASE_ROUTE__ || '';

const router = createRouter({
  history: createWebHistory(baseRoute),
  routes: [...]
});

📖 API 文档

xMicro.registerApps(apps)

注册子应用配置。

参数 类型 必填 说明
apps Array 是 子应用配置数组

子应用配置项：

参数 类型 必填 说明
name string 是 子应用名称，唯一标识
entry string 是 子应用入口地址
activeRule string/Function 是 激活规则（路由匹配）
container string 是 挂载容器选择器
props Object 否 传递给子应用的参数
sandbox boolean 否 是否启用沙箱，默认 true
preload boolean 否 是否预加载，默认 true

xMicro.start(options)

启动微前端框架。

参数 类型 默认值 说明
options.prefetch boolean true 是否预加载
options.sandbox boolean true 是否启用沙箱

xMicro.loadApp(name)

手动加载指定应用。

await xMicro.loadApp('vue-app');

xMicro.unloadApp(name)

手动卸载指定应用。

await xMicro.unloadApp('vue-app');

xMicro.getState()

获取全局状态。

const state = xMicro.getState();
console.log(state);

xMicro.setState(key, value)

设置全局状态。

xMicro.setState('user', { name: 'test' });

xMicro.on(event, callback)

订阅事件。

xMicro.on('app-mounted', (app) => {
  console.log('应用已挂载:', app);
});

xMicro.emit(event, ...args)

触发事件。

xMicro.emit('custom-event', { data: 'test' });

🌐 环境变量

框架会在子应用执行前注入以下全局变量：

变量名 说明
__POWERED_BY_XMICRO__ 是否在微前端环境中运行
__XMICRO_APP_NAME__ 当前子应用名称
__XMICRO_BASE_ROUTE__ 子应用基础路由
__XMICRO_ENTRY__ 子应用入口地址
__XMICRO_PUBLIC_PATH__ 子应用公共路径

🛡️ 沙箱机制

Proxy 沙箱

使用 ES6 Proxy 实现完全隔离的沙箱环境，子应用对 window 的修改不会影响其他应用。

ES 模块沙箱

专门为 ES 模块应用设计的沙箱，通过快照机制实现隔离。

快照沙箱（降级方案）

在不支持 Proxy 的浏览器中自动降级为快照沙箱。

🎨 CSS 隔离

框架默认使用命名空间方式隔离样式：

<!-- 子应用容器会添加命名空间 -->
<div id="subapp" data-micro-app="vue-app" class="micro-app-vue-app">
  <!-- 子应用内容 -->
</div>

⚠️ 注意事项

CORS 配置

子应用服务器必须配置 CORS，允许跨域访问：

# 使用 http-server
npx http-server -p 8081 --cors

# Vite 项目配置
// vite.config.js
export default {
  server: {
    cors: true
  }
}

路由配置

使用 History 路由时，建议子应用根据 __XMICRO_BASE_ROUTE__ 配置基础路由：

// Vue Router
const router = createRouter({
  history: createWebHistory(window.__XMICRO_BASE_ROUTE__ || ''),
  routes
});

// React Router
<BrowserRouter basename={window.__XMICRO_BASE_ROUTE__ || ''}>
  <Routes>...</Routes>
</BrowserRouter>

开发环境

Vite 开发模式下，子应用的 HMR 可以正常工作。

📊 与主流框架对比

特性 xMicro qiankun micro-app wujie
ES 模块支持 ✅ 原生 ⚠️ 有限 ⚠️ 有限 ✅ 支持
子应用改造 可选 必须 几乎无感 几乎无感
构建工具依赖 无 无 无 无
包体积 ~15KB ~45KB ~20KB ~30KB

🔧 开发

# 安装依赖
pnpm install

# 开发模式
pnpm dev

# 构建
pnpm build

# 测试
pnpm test

📝 更新日志

v1.0.16

  • ✨ 新增 ES 模块沙箱支持
  • ✨ 新增路由隔离变量注入
  • 🐛 修复 ES 模块应用加载时机问题
  • 📝 完善文档

📄 License

MIT