@composy/engine-vue

@composy/engine-vue

@composy/engine-vue 是 LDesign Engine 的 Vue 3 适配包。它建立在 @composy/engine-core 之上，只处理 Vue 应用挂载、依赖注入、组合式 API、组件和 Vue 生态可选集成。

适配层边界

• 复用 core 的插件、生命周期、状态、事件、中间件、配置、错误处理和性能监控。
• 本包只增加 Vue 相关能力：createApp()、mount()、unmount()、provide/inject、组件、组合式 API 和 Vue DevTools。
• router/i18n 是可选集成。Router 默认把缺失依赖或安装失败作为错误抛出，只有传入 optional: true 才会降级为警告；启用 i18n 时需提供 @composy/i18n-core 与 @composy/i18n-vue。

主要能力

• createVueEngine() / VueEngine：创建并管理 Vue 应用级引擎。
• EngineProvider：在组件树中提供引擎上下文。
• ErrorBoundary：Vue 组件错误边界。
• useEngine()、useEngineState()、useEngineEvent()：访问 core 引擎、状态和事件。
• useAsyncState()、useComputedState()、useDebouncedState()、usePersistentState()：Vue 化状态工具。
• usePluginApi()、useMiddleware()、usePerformance()、useTimeTravel()：复用 core 的运行时能力。
• createRouterPlugin()、createI18nPlugin()：可选生态桥接。
• createVueDevtoolsAdapter()：将 core 状态、事件和时间旅行接入 Vue DevTools。

配置中的插件会在 core init() 前安装，因此可以参与 beforeInit、init 与 afterInit。mount() 的并发调用复用同一启动过程；destroy() 或 unmount() 后该实例为终态，需创建新的 VueEngine 才能重新挂载。

engine.registerService(name, value) 返回 ServiceLease。插件应保存租约并在自己的 uninstall() 中 await lease.dispose()；释放操作只影响该插件创建的注册代次。i18n bridge 会同时释放字符串/Symbol service、清除 engine.i18n 并销毁其 owned i18n 实例。

快速开始

import { createVueEngine } from '@composy/engine-vue'
import App from './App.vue'

const engine = createVueEngine({
  name: 'ldesign-vue-app',
  debug: import.meta.env.DEV,
  app: {
    rootComponent: App,
    rootProps: {
      tenant: 'demo',
    },
  },
})

await engine.mount('#app')

组件内使用：

<script setup lang="ts">
import { useEngine, useEngineState } from '@composy/engine-vue'

const engine = useEngine()
const ready = useEngineState<boolean>('ready', false)

function markReady(): void {
  engine.events.emit('app:ready')
  ready.value = true
}
</script>

<template>
  <button type="button" @click="markReady">
    {{ ready ? 'ready' : 'booting' }}
  </button>
</template>

目录结构

src/
  components/    # EngineProvider、ErrorBoundary
  composables/   # useEngine/useAsyncState/usePerformance 等
  config/        # Vue 应用配置类型与 defineConfig
  devtools/      # Vue DevTools 桥接
  engine/        # VueEngine
  plugins/       # router/i18n 等可选插件
  style/         # 组件样式
  index.ts       # 统一公开入口

构建产物

dist/  # UMD/browser 产物、CSS 和 index.min.js
es/    # ESM 主产物、CSS 和 .d.ts
esm/   # 保留模块结构的 ESM/Less 产物
lib/   # CommonJS 产物

build 使用 .ldesign/builder.config.ts 中的 @composy/builder / Rolldown；ESLint 与 TypeScript 权威配置也位于 .ldesign/，旧根目录配置路径保留兼容 shim。构建后会归一化 dist/index.min.js、声明文件与 lib/package.json，outputs:check 验证 exports 和产物。

样式入口：

• @composy/engine-vue/index.css
• @composy/engine-vue/index.min.css

验证命令

pnpm run lint:check
pnpm run type-check
pnpm run test
pnpm run test:performance
pnpm run build

从工作区根目录可运行：

pnpm run build:vue
pnpm run playground:dev:vue
pnpm run playground:build:vue
pnpm run outputs:check

维护规则

• Vue 层新增能力前，先确认是否能在 @composy/engine-core 中实现为框架无关 API。
• Vue composable 只负责把 core 状态和生命周期映射成 ref、computed、watch 等 Vue 习惯用法。
• Vue 插件只负责安装到 Vue App 或向 core 插件上下文补充 Vue 信息，不应改变 core 插件协议。
• 测试优先覆盖源码入口，不依赖构建产物。