@composy/feature-flag-vue

@composy/feature-flag-vue

@composy/feature-flag-vue 是 @composy/feature-flag-core 的 Vue 3 适配层。它不重新实现开关评估、Provider、Engine 状态同步等核心逻辑,只负责 Vue App 注入、组合式 API、指令和 Vue Engine 挂载。

✨ 核心能力

• 统一插件入口:createFeatureFlagPlugin() 同一个对象既能走 app.use(),也能走 engine.use();createFeatureFlagVuePlugin / createFeatureFlagEnginePlugin 为语义别名。
• 组合式 API:useFeatureFlag(name, defaultValue?) 返回 enabled / value 响应式计算属性;useFeatureFlags(names) 批量返回布尔快照,通过共享 runtime 订阅避免重复监听。
• v-feature 指令:v-feature="'flag'" 开关开启时显示元素;v-feature:hide="'flag'" 反向隐藏;由 createFeatureDirective(manager) 创建。
• 上下文注入:provideFeatureFlagManager() / useFeatureFlagManager() / useFeatureFlagRuntime() 管理实例传递,含向后兼容的 FLAG_MANAGER_KEY。
• Engine 桥接:安装到 Engine 时复用 core 的 engine plugin 注册 state / API / events,Vue App 已存在则立即注入,否则监听 app:created 后再安装。
• 透传 core 能力:从本包可直接导入 FlagManager 与三种 Provider 及全部公共类型。

📦 安装

pnpm add @composy/feature-flag-vue

• 直接依赖:@composy/feature-flag-core
• peer 依赖:vue ^3.5.32

🚀 快速开始

import { createFeatureFlagPlugin, LocalProvider } from '@composy/feature-flag-vue'
import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App)

app.use(
  createFeatureFlagPlugin({
    provider: new LocalProvider({
      'new-dashboard': true,
      'export-pdf': false,
    }),
  })
)

app.mount('#app')

<script setup lang="ts">
import { useFeatureFlag } from '@composy/feature-flag-vue'

const { enabled, value } = useFeatureFlag('new-dashboard')
</script>

<template>
  <NewDashboard v-if="enabled" />
  <LegacyDashboard v-else />
  <pre>{{ value }}</pre>
</template>

指令

<template>
  <ExportButton v-feature="'export-pdf'" />
  <LegacyPanel v-feature:hide="'new-dashboard'" />
</template>

📖 API / 配置参考

插件

常用插件选项:provider(FlagProvider 实例)、autoLoad(安装后自动 load())、name(Engine state/API 命名空间)、destroyOnEngineUnmount(仅销毁插件自有 Manager)。

直接安装到 Vue App 时,插件会在 app.unmount() 前自动移除全局属性、指令和 Runtime 订阅；如果 Manager 由插件创建,也会同步销毁 Manager。通过 Engine 安装时,Vue 绑定只会在 core readiness 成功后注入,失败会回滚已创建的绑定。

组合式 API

注入与指令

Engine state / 事件常量

State:FEATURE_FLAG_MANAGER_STATE_KEY、FEATURE_FLAG_FLAGS_STATE_KEY、FEATURE_FLAG_CONTEXT_STATE_KEY、FEATURE_FLAG_CONFIG_STATE_KEY;事件:FEATURE_FLAG_INSTALLED_EVENT、FEATURE_FLAG_UPDATED_EVENT、FEATURE_FLAG_UNINSTALLED_EVENT,与 core 的 featureFlagStateKeys / featureFlagEventKeys 一致。

Engine 用法

import { createVueEngine } from '@composy/engine-vue'
import { createFeatureFlagEnginePlugin, RemoteProvider } from '@composy/feature-flag-vue'

createVueEngine({
  plugins: [
    createFeatureFlagEnginePlugin({
      provider: new RemoteProvider('/api/feature-flags'),
      autoLoad: true,
    }),
  ],
})

安装到 Engine 时,Vue 适配层会优先把 FlagManager 交给 core engine plugin 注册 state、API 和事件;Vue App 已存在则立即安装 provide 和指令,尚未创建则监听 app:created 后再安装。

延迟创建的 App 会受到 Engine 安装代次保护：卸载后到达的旧 app:created 事件不会重新注入指令或全局属性。

复用 core 的 Provider

import {
  FlagManager,
  LocalProvider,
  RemoteProvider,
  StorageProvider,
} from '@composy/feature-flag-vue'

const manager = new FlagManager({
  provider: new LocalProvider({ dashboard: true }),
})
await manager.load()

const remoteProvider = new RemoteProvider('/api/feature-flags')
await remoteProvider.load()
new StorageProvider().save(manager.getAll())

如需自定义开关评估、远程转换或缓存策略,应优先在 core 层扩展,再由本包复用。

🔨 构建产物与验证

产物目录:dist(浏览器构建)、es(ESM preserve modules + 类型声明)、esm(兼容 ESM 消费)、lib(CommonJS)。

pnpm --filter @composy/feature-flag-vue typecheck   # 类型检查
pnpm --filter @composy/feature-flag-vue build      # 构建
pnpm --filter @composy/feature-flag-vue test:run   # 单元测试
pnpm --filter @composy/feature-flag-vue lint:check # ESLint 检查

维护约定:Vue 层只处理生命周期、注入、指令和组合式 API;Engine 状态/API 注册必须复用 core 的 createFeatureFlagEnginePlugin;新增行为需补充 src/__tests__ 运行时测试。

🔗 相关链接

• 上级工作区:LDesign FeatureFlag
• 核心实现层:@composy/feature-flag-core

工程配置

Vue adapter 的权威 ESLint、生产 TypeScript 和测试 TypeScript 配置位于 .ldesign/；包根配置文件仅作为兼容 shim。构建使用 @composy/builder 与 Rolldown，postbuild 会按 LDesignFeatureFlagVue 归一化压缩 UMD 入口并检查发布产物。