@micro-app-adapter/vue3-vite

v1.0.2

Published

14 hours ago

Micro-app lifecycle adapter for Vue3 + Vite sub-app-applications

0High
0Medium
0Low

zhichao.xu

micro-app vue3 vite adapter

@micro-app-adapter/vue3-vite

Vue 3 + Vite 项目的微前端生命周期适配器，帮助 Vue 3 子应用快速接入微前端框架。

功能特性

核心功能

| 功能模块 | 功能描述 | 关键API | |---------|---------|--------| | 生命周期管理 | 自动注册 mount/unmount 生命周期到 window 对象 | registerVueMicroApp | | 独立运行支持 | 非微前端环境下自动启动应用，无需修改代码 | 自动检测 __MICRO_APP_ENVIRONMENT__ | | 路由同步 | 主子应用路由双向同步，支持声明式和编程式导航 | MicroAppRouter, useMicroAppNavigate | | 数据通信 | 监听主应用下发的数据变化，支持路由事件监听 | MicroAppDataListener, useMicroAppDataListener | | 环境判断 | 检测微前端运行环境，获取基础路由等信息 | isMicroApp, getBasename | | TypeScript 支持 | 完整的类型定义，提供良好的开发体验 | 所有API均有类型定义 |

技术特点

| 特性 | 说明 | |-----|------| | 🚀 ESM 输出 | 原生 ES Module 输出格式，符合 Vite 生态最佳实践 | | 📦 零配置 | 开箱即用，无需复杂的构建配置 | | 🎯 组合式 API | 提供完整的 Composition API 支持，符合 Vue 3 最佳实践 | | 💪 TypeScript | 完整类型支持，提供优秀的IDE提示 | | 🧩 组件化 | 提供开箱即用的路由组件，简化开发流程 | | 🔧 无需 public-path | Vite 原生支持 ESM，无需配置动态公共路径 |

安装

pnpm add @micro-app-adapter/vue3-vite

# 或
npm install @micro-app-adapter/vue3-vite

# 或
yarn add @micro-app-adapter/vue3-vite

版本要求

| 依赖包 | 版本要求 | 说明 | |-------|---------|------| | Vue | >=3.0.0 | 支持 Vue 3 组合式 API | | Vue-Router | >=4.0.0 | 可选，路由同步功能需要 |

Vue 3 版本兼容性详情

| Vue 版本 | 支持状态 | 说明 | |---------|---------|------| | Vue 3.5+ | ✅ 完整支持 | 推荐版本，最新特性 | | Vue 3.0-3.4 | ✅ 完整支持 | 稳定版本 |

Vue-Router 版本兼容性

| Vue-Router 版本 | 支持状态 | 说明 | |----------------|---------|------| | Vue-Router 4.x | ✅ 完整支持 | 与 Vue 3 配套使用 | | Vue-Router 3.x | ❌ 不支持 | 适用于 Vue 2，请使用 Vue 2 适配器 |

快速开始

1. 基础接入

// main.ts
import { createApp } from 'vue';
import App from './App.vue';
import router from './router';
import { registerVueMicroApp } from '@micro-app-adapter/vue3-vite';

// 注册微前端生命周期
registerVueMicroApp(App, {
  appName: 'vue3-vite-sub-app',
  router,           // 可选
  mountId: '#app'   // 可选，默认 '#app'
});

2. 路由同步方案

方案一：使用 MicroAppRouter 组件（推荐）

<!-- App.vue -->
<template>
  <MicroAppRouter
    :routes="routes"
    default-path="/home"
    :basename="basename"
    history-mode="hash"
  />
</template>

<script setup lang="ts">
import { MicroAppRouter, RouteConfig, getBasename } from '@micro-app-adapter/vue3-vite';
import Home from './pages/Home.vue';
import About from './pages/About.vue';
import User from './pages/User.vue';

const basename = getBasename();

const routes: RouteConfig[] = [
  { path: '/home', component: Home },
  { path: '/about', component: About },
  { path: '/user', component: User },
];
</script>

方案二：使用 MicroAppRouteView + MicroAppDataListener

<!-- App.vue -->
<template>
  <div v-if="isMicroApp()">
    <MicroAppDataListener :on-route-change="handleRouteChange" />
    <MicroAppRouteView 
      :routes="routes" 
      default-path="/home"
      :fallback="NotFound"
    />
  </div>
  <div v-else>
    <!-- 独立运行时的路由 -->
    <router-view />
  </div>
</template>

<script setup lang="ts">
import { 
  isMicroApp, 
  MicroAppDataListener, 
  MicroAppRouteView,
  RouteConfig 
} from '@micro-app-adapter/vue3-vite';
import NotFound from './pages/NotFound.vue';

const routes: RouteConfig[] = [
  { path: '/home', component: Home },
  { path: '/about', component: About },
];

const handleRouteChange = (data: { path: string; event?: string }) => {
  console.log('路由变化:', data.path, data.event);
};
</script>

方案三：手动路由同步（使用 Composition API）

<!-- App.vue -->
<template>
  <div>
    <MicroAppDataListener />
    <component :is="currentComponent" />
  </div>
</template>

<script setup lang="ts">
import { computed, watch } from 'vue';
import { 
  isMicroApp, 
  useMicroAppRouteSync, 
  useMicroAppNavigate,
  MicroAppDataListener 
} from '@micro-app-adapter/vue3-vite';

const { ready, targetPath } = useMicroAppRouteSync();
const { navigate } = useMicroAppNavigate();

// 根据路径动态渲染组件
const currentComponent = computed(() => {
  if (!ready.value) return null;
  // 根据targetPath返回对应组件
  return getComponentByPath(targetPath.value);
});

// 监听路由变化
watch(targetPath, (newPath) => {
  console.log('目标路径:', newPath);
});
</script>

API 文档

registerVueMicroApp

function registerVueMicroApp(
  AppComponent: Component,
  options: RegisterVueMicroAppOptions
): void;

interface RegisterVueMicroAppOptions {
  appName: string;      // 子应用名称
  router?: Router;      // Vue Router 实例（可选）
  mountId?: string;     // 挂载容器选择器，默认 '#app'
}

使用示例：

import { createApp } from 'vue';
import { createRouter, createWebHistory } from 'vue-router';
import App from './App.vue';
import { registerVueMicroApp } from '@micro-app-adapter/vue3-vite';

const router = createRouter({
  history: createWebHistory(),
  routes: [
    { path: '/home', component: Home },
    { path: '/about', component: About },
  ]
});

registerVueMicroApp(App, {
  appName: 'vue3-sub-app',
  router,
  mountId: '#app'
});

生命周期注册规则：

注册到 window['micro-app-{appName}']
提供 mount 和 unmount 方法
非微前端环境自动调用 mount

isMicroApp

判断当前是否运行在微前端环境。

function isMicroApp(): boolean;

使用示例：

<template>
  <div v-if="isMicroApp()">微前端环境</div>
  <div v-else>独立运行</div>
</template>

<script setup>
import { isMicroApp } from '@micro-app-adapter/vue3-vite';
</script>

getBasename

获取微前端基础路由。

function getBasename(): string;

使用示例：

const basename = getBasename(); // 返回 '/sub-app' 或 '/'

createMicroAppRouteState

创建路由状态管理对象。

function createMicroAppRouteState(): MicroAppRouteState;

interface MicroAppRouteState {
  ready: boolean;
  targetPath: string;
  listeners: Set<() => void>;
  subscribe: (listener: () => void) => () => void;
  notify: () => void;
  setPath: (path: string) => void;
  reset(): void;
}

useMicroAppRouteSync

获取路由同步状态的 Hook。

function useMicroAppRouteSync(): UseMicroAppRouteSyncResult;

interface UseMicroAppRouteSyncResult {
  ready: Ref<boolean>;      // 路由是否就绪
  targetPath: Ref<string>;  // 目标路径
}

使用示例：

<template>
  <div v-if="!ready">加载中...</div>
  <div v-else>当前路径: {{ targetPath }}</div>
</template>

<script setup>
import { useMicroAppRouteSync } from '@micro-app-adapter/vue3-vite';

const { ready, targetPath } = useMicroAppRouteSync();
</script>

useMicroAppNavigate

获取导航函数的 Hook。

function useMicroAppNavigate(): { navigate: (path: string) => void };

使用示例：

<template>
  <button @click="handleNavigate('/home')">跳转首页</button>
  <button @click="handleNavigate('/about')">跳转关于</button>
</template>

<script setup>
import { useMicroAppNavigate } from '@micro-app-adapter/vue3-vite';

const { navigate } = useMicroAppNavigate();

const handleNavigate = (path: string) => {
  navigate(path);
  // 微前端环境：同步到主应用
  // 独立运行：更新 hash 路由
};
</script>

导航行为：

| 环境 | 行为 | |-----|------| | 微前端环境 | 更新状态 + 通知主应用 + 同步到全局数据 | | 独立运行 | 更新 hash 路由 |

useMicroAppDataListener

数据监听 Hook。

function useMicroAppDataListener(
  onRouteChange?: (data: { path: string; event?: string }) => void
): void;

使用示例：

<script setup>
import { useMicroAppDataListener } from '@micro-app-adapter/vue3-vite';

useMicroAppDataListener((data) => {
  console.log('路径:', data.path);
  console.log('事件:', data.event);
});
</script>

MicroAppDataListener

数据监听组件。

interface MicroAppDataListenerProps {
  onRouteChange?: (data: { path: string; event?: string }) => void;
}

const MicroAppDataListener: Component;

使用示例：

<template>
  <MicroAppDataListener :on-route-change="handleRouteChange" />
</template>

<script setup>
import { MicroAppDataListener } from '@micro-app-adapter/vue3-vite';

const handleRouteChange = (data) => {
  console.log('路由变化:', data);
};
</script>

事件类型：

| 事件 | 说明 | |-----|------| | beforeShow | 子应用即将显示 | | afterShow | 子应用已显示 | | undefined | 普通路由切换 |

MicroAppRouteView

路由视图组件。

interface MicroAppRouteViewProps {
  routes: RouteConfig[];       // 路由配置
  defaultPath?: string;        // 默认路径，默认 '/home'
  fallback?: Component;        // 找不到路由时的回退组件
}

interface RouteConfig {
  path: string;
  component: Component;
  children?: RouteConfig[];    // 支持嵌套路由
}

const MicroAppRouteView: Component;

使用示例：

<template>
  <MicroAppRouteView 
    :routes="routes" 
    default-path="/home"
    :fallback="NotFound"
  />
</template>

<script setup>
import { MicroAppRouteView } from '@micro-app-adapter/vue3-vite';
import NotFound from './pages/NotFound.vue';

const routes = [
  { path: '/home', component: Home },
  { path: '/about', component: About },
  { 
    path: '/user', 
    component: User,
    children: [
      { path: '/user/profile', component: Profile }
    ]
  },
];
</script>

MicroAppRouter

一体化路由组件，自动处理微前端和独立运行两种模式。

interface MicroAppRouterProps {
  routes: RouteConfig[];
  defaultPath?: string;        // 默认 '/home'
  basename?: string;           // 基础路径，默认 '/'
  historyMode?: 'hash' | 'history';  // 路由模式，默认 'hash'
  fallback?: Component;        // 回退组件
}

const MicroAppRouter: Component;

特性：

微前端环境：使用内置路由系统，监听主应用数据
独立运行：使用简单的 hash/history 路由
自动处理路由同步和状态管理
提供 router context 供子组件使用

使用示例：

<template>
  <MicroAppRouter
    :routes="routes"
    default-path="/home"
    basename="/sub-app"
    history-mode="hash"
  />
</template>

<script setup>
import { MicroAppRouter, getBasename } from '@micro-app-adapter/vue3-vite';

const basename = getBasename();

const routes = [
  { path: '/home', component: Home },
  { path: '/about', component: About },
];
</script>

类型导出

// 接口类型
export type { 
  RegisterVueMicroAppOptions,
  MicroAppLifecycle,
  MicroAppRouteState,
  UseMicroAppRouteSyncResult,
  RouteConfig,
  MicroAppRouterProps
};

全局类型扩展

declare global {
  interface Window {
    __MICRO_APP_ENVIRONMENT__: boolean;  // 是否微前端环境
    __MICRO_APP_NAME__: string;          // 子应用名称
    __MICRO_APP_BASE_URL__: string;      // 基础URL
    __MICRO_APP_PUBLIC_PATH__: string;   // 公共路径
    [key: string]: any;
  }
}

主应用配置示例

<micro-app 
  name="vue3-vite-sub-app"
  url="http://localhost:5173"
  baseroute="/sub-app"
></micro-app>

完整示例

// main.ts
import { registerVueMicroApp } from '@micro-app-adapter/vue3-vite';
import App from './App.vue';
import router from './router';

registerVueMicroApp(App, {
  appName: 'vue3-vite-sub-app',
  router,
  mountId: '#app'
});

<!-- App.vue -->
<template>
  <MicroAppRouter
    :routes="routes"
    default-path="/home"
    :basename="basename"
  />
</template>

<script setup lang="ts">
import { MicroAppRouter, RouteConfig, getBasename } from '@micro-app-adapter/vue3-vite';
import Home from './pages/Home.vue';
import About from './pages/About.vue';

const basename = getBasename();

const routes: RouteConfig[] = [
  { path: '/home', component: Home },
  { path: '/about', component: About },
];
</script>

开发调试

# 安装依赖
pnpm install

# 开发模式
pnpm dev

# 构建
pnpm build

注意事项

不需要 public-path: Vite 项目无需配置 public-path
Vue 版本: 要求 Vue 3.0+
路由库: 可选使用 vue-router 4.0+，或使用内置路由组件
构建输出: 仅输出 ESM 格式

与 vue3-webpack 版本的差异对比

| 特性 | vue3-vite | vue3-webpack | |-----|----------|--------------| | 输出格式 | ESM | ESM + CJS | | public-path | 不需要 | 必须引入 | | route-sync 独立入口 | ❌ 无 | ✅ 支持 | | 构建工具 | Vite | Webpack | | 浏览器兼容性 | 现代浏览器 | 更广泛 | | 开发体验 | 热更新更快 | 生态更成熟 | | 适用场景 | 新项目、现代浏览器 | 旧项目迁移、广泛兼容 |

如何选择？

选择 vue3-vite：新项目、使用 Vite 构建、目标用户使用现代浏览器
选择 vue3-webpack：需要广泛浏览器支持、从旧项目迁移、使用 Webpack 构建

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@micro-app-adapter/vue3-vite

功能特性

核心功能

技术特点

安装

版本要求

Vue 3 版本兼容性详情

Vue-Router 版本兼容性

快速开始

1. 基础接入

2. 路由同步方案

方案一：使用 MicroAppRouter 组件（推荐）

方案二：使用 MicroAppRouteView + MicroAppDataListener

方案三：手动路由同步（使用 Composition API）

API 文档

registerVueMicroApp

isMicroApp

getBasename

createMicroAppRouteState

useMicroAppRouteSync

useMicroAppNavigate

useMicroAppDataListener

MicroAppDataListener

MicroAppRouteView

MicroAppRouter

类型导出

全局类型扩展

主应用配置示例

完整示例

开发调试

注意事项

与 vue3-webpack 版本的差异对比

如何选择？

License