Справочник

Типы TypeScript

Все публичные типы экспортируются из корня пакета:

import type {
  FeatureTogglesOptions,
  FeatureProvider,
  FlagSource,
  FlagValue,
  FlagMeta,
  FlagName,
  SetFlagOptions,
  LiveUpdatesOptions,
} from 'vue-feature-toggles'

// FlagValue — boolean ИЛИ строка варианта
type FlagValue = boolean | string

// Все уровни источника флага
type FlagSource = 'url' | 'runtime' | 'rules' | 'loader' | 'static' | 'default'

interface FlagMeta {
  description?: string
  owner?: string
  addedAt?: string // строка ISO-даты, напр. '2025-03-01'
  ticket?: string
}

interface SetFlagOptions {
  persist?: boolean // сохранить в localStorage
}

interface LiveUpdatesOptions {
  type: 'sse' | 'websocket'
  url: string
  reconnectDelay?: number // мс, по умолчанию: 3000
}

// FlagName разрешается в union объявленных вами имён флагов при дополнении FeatureFlagNames,
// либо откатывается к string, когда он пуст.
type FlagName = keyof FeatureFlagNames extends never ? string : keyof FeatureFlagNames

Типобезопасность

Расширьте встроенный интерфейс FeatureFlagNames, чтобы получить автодополнение и ошибки компиляции по именам флагов везде — useFeature, setFlag, isEnabled, <Feature name="..."> и т. д.

// feature-flags.d.ts (или любой .d.ts файл в вашем проекте)
declare module 'vue-feature-toggles' {
  interface FeatureFlagNames {
    newDashboard: true
    betaSearch: true
    darkMode: true
  }
}

useFeature('newDashbord') // Ошибка TS: аргумент типа '"newDashbord"' не может быть присвоен
useFeature('newDashboard') // ✔

Экспорты

// Основная точка входа — vue-feature-toggles
import {
  FeatureToggles, // плагин для app.use()
  Feature, // компонент <Feature>
  FeatureVariant, // компонент <FeatureVariant>
  FeatureDevTools, // оверлей DevTools
  vFeature, // директива v-feature
  useFeature, // composable
  useFeatureVariant, // composable для вариантных флагов
  useFeatureProvider, // низкоуровневый composable
  FEATURE_PROVIDER_KEY,
} from 'vue-feature-toggles'

import type {
  FeatureTogglesOptions,
  FeatureProvider,
  FlagSource,
  FlagValue,
  FlagMeta,
  FlagName,
  SetFlagOptions,
  LiveUpdatesOptions,
} from 'vue-feature-toggles'

// Утилиты для тестирования (исключены из продакшен-бандла)
import {
  createTestFeatureProvider,
  withFeatures,
  setTestFlag,
  resetTestProvider,
} from 'vue-feature-toggles/testing'

// Декоратор Storybook (исключён из продакшен-бандла)
import { withFeatureToggles } from 'vue-feature-toggles/storybook'

// Адаптеры-загрузчики (LaunchDarkly, Unleash, Flagsmith)
import { launchDarklyLoader, unleashLoader, flagsmithLoader } from 'vue-feature-toggles/adapters'

// Плагин Vite — удаляет <FeatureDevTools> в продакшен-сборках
import { featureTogglesPlugin } from 'vue-feature-toggles/vite'

// Модуль Nuxt
// modules: ['vue-feature-toggles/nuxt']

Архитектура

vue-feature-toggles
│
├── FeatureProvider  (основной синглтон, создаётся плагином)
│     FlagStore        — Map<name, FlagValue>; реактивен через shallowRef
│     SourceIndex      — Map<name, FlagSource>; уровень приоритета для каждого флага
│     VariableStore    — Map<flagName+varName, Ref<T>>
│     ProfileStore     — читает/пишет именованные снимки в localStorage
│
├── Цепочка приоритетов  (от высшего к низшему)
│     UrlOverrideLayer   — читает query-параметры при инициализации; реактивно обновляется через URLSearchParams
│     RuntimeLayer       — setFlag() / setVariant() / setVariable(); опция persist → localStorage
│     RulesLayer         — отслеживает реактивные функции правил; переоценивает при изменении зависимостей
│     LoaderLayer        — асинхронный loader; опциональный поллинг через setInterval; слушатель живых обновлений
│     StaticLayer        — флаги/переменные из опций плагина
│     DefaultLayer       — откат к defaultValue
│
├── DependencyManager
│     Вычисляет принудительно отключённые флаги, когда требуемые флаги выключены
│     Выводит предупреждения в dev-консоль при нарушении; предоставляет getDependencyViolations()
│
├── GroupManager
│     setGroup() распространяется на все флаги-участники через RuntimeLayer
│     isGroupEnabled() синхронно проверяет всех участников
│
├── ExpiryManager
│     Сравнивает даты meta.expiry с Date.now() при каждом вызове isEnabled()
│     Истёкшие флаги возвращают defaultValue; предупреждение в dev-консоли при первом обращении
│
├── LiveUpdatesManager
│     SSE — EventSource; автопереподключение при ошибке
│     WebSocket — нативный WebSocket; настраиваемый reconnectDelay
│     Оба сливают полученный частичный объект флагов в LoaderLayer
│
├── <Feature> / <FeatureVariant>
│     Инжектируют FEATURE_PROVIDER_KEY; рендерят через computed isEnabled / getVariant
│     Слот loading показывается, пока isLoading.value равен true
│
├── Директива v-feature
│     Хуки beforeMount + updated; устанавливает el.style.display на основе значения флага
│
├── useFeature / useFeatureVariant
│     Тонкие обёртки, возвращающие вычисляемые Ref из FeatureProvider
│
├── <FeatureDevTools>
│     Оверлей с тремя вкладками: Flags · Groups · History
│     Перетаскивание через mousedown + mousemove; позиция сохраняется в sessionStorage
│     Читает/пишет напрямую через useFeatureProvider()
│
├── Интеграция DevTools  (опциональный @vue/devtools-api)
│     Загружается динамически; тихо пропускается при отсутствии пакета
│     Инспектор: все флаги с бейджами источника
│     Таймлайн: события изменения флагов с предыдущим/новым значением
│
├── /testing  (отдельная точка входа)
│     createTestFeatureProvider — изолированный FeatureProvider, без побочных эффектов в localStorage
│     withFeatures — сокращение для опций монтирования @vue/test-utils
│     setTestFlag — устанавливает флаг + дожидается nextTick
│     resetTestProvider — очищает все runtime-переопределения
│
├── /storybook  (отдельная точка входа)
│     withFeatureToggles — декоратор Storybook; объединяет параметры истории поверх глобальных значений по умолчанию
│
├── /adapters  (отдельная точка входа)
│     launchDarklyLoader, unleashLoader, flagsmithLoader
│     Каждый возвращает async () => Record<string, FlagValue>, совместимый с опцией loader
│
├── /vite  (отдельная точка входа)
│     featureTogglesPlugin — трансформация Vite, удаляющая <FeatureDevTools> в продакшене
│
└── /nuxt  (модуль)
      Регистрирует <Feature>, <FeatureVariant>, v-feature глобально через addComponent / addDirective
      Устанавливает плагин через addPlugin с runtimeConfig.featureToggles
      Обрабатывает SSR-состояние через nuxtApp.payload (конфигурация ssrState не нужна)

Размер бандла и peer-зависимости

Точка входа	Peer-зависимости	Примечания
`vue-feature-toggles`	`vue ^3.0`	Ядро — плагин, компоненты, директива, composables
`vue-feature-toggles/testing`	`vue ^3.0`	Только тестовые хелперы; исключено из продакшен-бандла
`vue-feature-toggles/storybook`	`vue ^3.0`	Только декоратор Storybook; исключено из продакшена
`vue-feature-toggles/adapters`	`vue ^3.0`	Загрузчики LaunchDarkly, Unleash, Flagsmith
`vue-feature-toggles/vite`	`vite ^4`	Трансформирующий плагин Vite
`vue-feature-toggles/nuxt`	`vue ^3.0`, `@nuxt/kit` (опциональный peer)	Модуль Nuxt 3

Пакет поставляется как tree-shakeable ESM (dist/*.js) и CommonJS (dist/*.cjs). @vue/devtools-api — опциональная peer-зависимость: интеграция с DevTools загружается динамически и тихо пропускается, когда пакет отсутствует или Vue DevTools закрыты.

Лицензия

MIT

Справочник ​

Типы TypeScript ​

Типобезопасность ​

Экспорты ​

Архитектура ​

Размер бандла и peer-зависимости ​