npm package: @jserxiao/xmicro
Description: 一个轻量级的微前端框架
Author: jserxiao
Latest version: 1.0.17

# @jserxiao/xmicro

一个轻量级、渐进式的微前端框架，支持多框架集成、沙箱隔离、ES模块应用等特性。

## ✨ 特性

- 🚀 **轻量级** - 核心代码 gzip 后仅 ~15KB，无第三方依赖
- 🔒 **沙箱隔离** - Proxy 沙箱 + 快照沙箱降级方案
- 📦 **HTML Entry** - 支持 HTML Entry 方式加载子应用
- ⚡ **ES 模块支持** - 原生支持 Vite、Snowpack 等现代构建工具
- 🔄 **生命周期管理** - 完整的应用生命周期钩子
- 📡 **通信机制** - Props 传递 + 事件总线
- 🎨 **CSS 隔离** - 命名空间 + Shadow DOM 可选
- 🔗 **路由隔离** - 自动注入基础路由信息
- 🎯 **TypeScript 支持** - 完整的类型定义

## 📦 安装

```bash
# npm
npm install @jserxiao/xmicro

# yarn
yarn add @jserxiao/xmicro

# pnpm
pnpm add @jserxiao/xmicro
```

## 🚀 快速开始

### 主应用配置

```javascript
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();
```

### 子应用配置

#### 方式一：导出生命周期钩子（推荐）

```javascript
// 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 };
```

```javascript
// 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 项目），框架会自动处理，无需修改子应用代码。

但建议在子应用中检测微前端环境，以适配路由：

```javascript
// 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)

手动加载指定应用。

```javascript
await xMicro.loadApp('vue-app');
```

### xMicro.unloadApp(name)

手动卸载指定应用。

```javascript
await xMicro.unloadApp('vue-app');
```

### xMicro.getState()

获取全局状态。

```javascript
const state = xMicro.getState();
console.log(state);
```

### xMicro.setState(key, value)

设置全局状态。

```javascript
xMicro.setState('user', { name: 'test' });
```

### xMicro.on(event, callback)

订阅事件。

```javascript
xMicro.on('app-mounted', (app) => {
  console.log('应用已挂载:', app);
});
```

### xMicro.emit(event, ...args)

触发事件。

```javascript
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 隔离

框架默认使用命名空间方式隔离样式：

```html
<!-- 子应用容器会添加命名空间 -->
<div id="subapp" data-micro-app="vue-app" class="micro-app-vue-app">
  <!-- 子应用内容 -->
</div>
```

## ⚠️ 注意事项

### CORS 配置

子应用服务器必须配置 CORS，允许跨域访问：

```bash
# 使用 http-server
npx http-server -p 8081 --cors

# Vite 项目配置
// vite.config.js
export default {
  server: {
    cors: true
  }
}
```

### 路由配置

使用 History 路由时，建议子应用根据 `__XMICRO_BASE_ROUTE__` 配置基础路由：

```javascript
// 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 |

## 🔧 开发

```bash
# 安装依赖
pnpm install

# 开发模式
pnpm dev

# 构建
pnpm build

# 测试
pnpm test
```

## 📝 更新日志

### v1.0.16

- ✨ 新增 ES 模块沙箱支持
- ✨ 新增路由隔离变量注入
- 🐛 修复 ES 模块应用加载时机问题
- 📝 完善文档

## 📄 License

MIT