Справочник

Типы TypeScript

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

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

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

// Значение опции flags — это либо обычное значение, либо определение процентного раската
type FlagDefinition = FlagValue | { value: FlagValue; rollout: number }

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

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

interface FlagSchedule {
  from?: string // ISO-дата — флаг принудительно выключен до этой даты
  to?: string // ISO-дата — флаг принудительно выключен после этой даты
}

interface SetFlagOptions {
  persist?: boolean // сохранить в localStorage — работает и для setFlag(), и для setVariant()
}

interface WatchFlagOptions {
  debounce?: number // мс — дебаунс коллбэка
  immediate?: boolean // вызвать коллбэк один раз сразу с текущим значением
}

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, // ключ инъекции, для собственных сценариев provide()/inject()
  serializeFlags, // хелпер для SSR
} from 'vue-feature-toggles'

import type {
  FeatureTogglesOptions,
  FeatureProvider,
  FlagSource,
  FlagValue,
  FlagDefinition,
  FlagName,
  FlagMeta,
  FlagSchedule,
  SetFlagOptions,
  WatchFlagOptions,
  LiveUpdatesOptions,
  FeatureFlagNames,
} 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/
├── src/
│   ├── core/
│   │   ├── FeatureProvider.ts   # createFeatureProvider() — весь провайдер как одна функция-
│   │   │                        #   фабрика: сливает цепочку приоритетов (url → runtime → rules
│   │   │                        #   → loader → static → schedule → default), затем применяет
│   │   │                        #   принудительное отключение по зависимостям; отдаёт каждый
│   │   │                        #   метод FeatureProvider
│   │   ├── rollout.ts           # hashToFloat() (FNV-1a), resolveFlagDef() — процентный раскат
│   │   ├── persistence.ts       # чтение/запись localStorage для runtime-переопределений + профилей
│   │   ├── live-updates.ts      # setupLiveUpdates() — SSE / WebSocket, автопереподключение,
│   │   │                        #   помечает полученные флаги источником 'live'
│   │   ├── helpers.ts           # isFlagTruthy, parseUrlValue, parseVarValue
│   │   └── types.ts             # FeatureTogglesOptions, FeatureProvider и все публичные типы
│   ├── components/
│   │   ├── feature.vue          # <Feature>
│   │   ├── feature-variant.vue  # <FeatureVariant>
│   │   └── feature-dev-tools.vue# <FeatureDevTools> — собран из внутренних src/ui/*.vue частей
│   ├── directives/
│   │   └── vFeature.ts          # v-feature
│   ├── composables/
│   │   ├── useFeature.ts        # useFeature, useFeatureVariant
│   │   └── useFeatureProvider.ts# useFeatureProvider
│   ├── ui/                      # собственные подкомпоненты FeatureDevTools — внутренние, не экспортируются
│   ├── plugin.ts                # FeatureToggles — точка входа app.use()
│   ├── devtools.ts              # setupVueDevtools() — подключение расширения Vue DevTools,
│   │                            #   вызывается автоматически из plugin.ts в dev-режиме, не экспортируется
│   ├── ssr.ts                   # serializeFlags()
│   ├── testing.ts               # точка входа /testing
│   ├── storybook.ts             # точка входа /storybook
│   ├── adapters.ts              # точка входа /adapters
│   ├── vite.ts                  # точка входа /vite
│   └── index.ts                 # корневая точка входа
├── nuxt/
│   ├── module.ts                # модуль Nuxt 3 (defineNuxtModule)
│   └── runtime/
│       └── plugin.ts            # runtime-плагин Nuxt — глобальная регистрация + обработка SSR-состояния
└── bin/
    └── cli.js                   # подкоманды list / check / stale

FeatureProvider.ts — это одна плоская функция-фабрика, а не набор классов-менеджеров: разрешение флага — это один computed(), который наслаивает URL-переопределения, runtime-переопределения, правила, результат loader, статические флаги и проверку расписания друг на друга в порядке приоритета, а затем применяет принудительное отключение по зависимостям. См. порядок приоритета для точной цепочки.

Размер бандла и 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`, что уже используется в проекте	Трансформирующий плагин Vite
`vue-feature-toggles/nuxt`	`vue ^3.0`, `@nuxt/kit ≥3.0` (опциональный peer)	Модуль Nuxt 3

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

Лицензия

MIT

Справочник ​

Типы TypeScript ​

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

Экспорты ​

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

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