FlipFlag SDK

Клиентская библиотека для работы с feature flags (TypeScript/JavaScript)

FlipFlag SDK — лёгкая клиентская библиотека для работы с feature flags. Поддерживает Node.js и браузер, работает в режиме только чтения (publicKey) или полного управления (publicKey + privateKey).

Установка

npm install @flipflag/sdk
# или
yarn add @flipflag/sdk
# или
pnpm add @flipflag/sdk

Быстрый старт

Node.js

import { FlipFlag } from "@flipflag/sdk";

const manager = new FlipFlag({
  publicKey: "YOUR_PUBLIC_KEY",
  privateKey: "YOUR_PRIVATE_KEY", // опционально
});

await manager.init();

if (manager.isEnabled("newFeature")) {
  console.log("Feature is enabled!");
}

Браузер (с inline-конфигурацией)

import { FlipFlag } from "@flipflag/sdk";

const manager = new FlipFlag(
  {
    publicKey: "YOUR_PUBLIC_KEY",
    privateKey: "YOUR_PRIVATE_KEY",
  },
  {
    newPaymentFlow: {
      description: "New Stripe integration",
      contributor: "payments-team@example.com",
      type: "feature",
    },
  }
);

await manager.init();

Режимы работы

Только чтение — только publicKey. Флаги загружаются с сервера, создавать и синхронизировать их нельзя. Подходит для фронтенда в продакшене.

Полный режим — publicKey + privateKey. Флаги декларируются, синхронизируются, трекается использование.

// Только чтение — безопасно для клиентского кода
const manager = new FlipFlag({
  publicKey: import.meta.env.VITE_FLIPFLAG_PUBLIC_KEY,
});

Не передавайте privateKey в клиентский код фронтенда — он даёт права на управление флагами.

Конфигурация

Опция	Тип	По умолчанию	Описание
`publicKey`	string	—	Публичный ключ (обязательный)
`privateKey`	string	—	Приватный ключ (опционально)
`apiUrl`	string	`https://api.flipflag.dev`	URL API-сервера
`configPath`	string	`./.flipflag.yml`	Путь до конфига (Node.js)
`ignoreMissingConfig`	boolean	`true`	Не бросать ошибку при отсутствии конфига
`pollingInterval`	number	`30000`	Интервал обновления флагов (мс)
`syncInterval`	number	`90000`	Интервал синхронизации деклараций и статистики (мс)

API

`init()`

Инициализирует SDK: загружает YAML-конфиг (Node.js), получает флаги с сервера, запускает polling и синхронизацию.

await manager.init();

`isEnabled(featureName)`

Возвращает true, если флаг включён. Автоматически трекает использование. Если флаг не существует на сервере и передан privateKey — создаёт его.

if (manager.isEnabled("darkMode")) {
  enableDarkMode();
}

`sync()`

Принудительная синхронизация без ожидания интервала.

await manager.sync();

`declareFromObject(config)`

Декларирует флаги программно (аналог YAML, для браузера).

manager.declareFromObject({
  experimentalUI: {
    contributor: "ui-team@example.com",
  },
});

`destroy()`

Останавливает polling и синхронизацию, очищает кэш.

manager.destroy();

YAML-конфигурация (Node.js)

SDK автоматически загружает .flipflag.yml из корня проекта при init().

newFeature:
  contributor: dev@example.com

seasonalBanner:
  description: "Holiday sale banner"
  contributor: marketing@example.com
  type: "feature"

abTest:
  description: "New checkout flow"
  contributor: analytics@example.com
  type: "experiment"

Кастомный путь:

const manager = new FlipFlag({
  publicKey: "pub_xxxxxxxxxxxxx",
  configPath: "./config/features.yml",
});

Трекинг экспериментов

Требует privateKey. События буферизуются и автоматически отправляются каждые syncInterval (90 сек) или при накоплении 500 событий.

Назначение на вариант (assignment)

manager.trackAssignment({
  experimentKey: "checkout-flow-v2",
  variant: "control",
  subjectType: "user",
  subjectId: "user_123",
});

Показ варианта (exposure)

manager.trackExposure({
  experimentKey: "checkout-flow-v2",
  variant: "treatment",
  subjectType: "user",
  subjectId: "user_123",
});

Метрика

// Простое событие конверсии
manager.trackMetric({
  experimentKey: "checkout-flow-v2",
  variant: "treatment",
  subjectType: "user",
  subjectId: "user_123",
  metricName: "purchase_completed",
});

// С числовым значением
manager.trackMetric({
  experimentKey: "checkout-flow-v2",
  variant: "treatment",
  subjectType: "user",
  subjectId: "user_123",
  metricName: "revenue",
  value: 49.99,
  properties: { currency: "USD" },
});

Типы субъектов:

Значение	Описание
`"user"`	Авторизованный пользователь
`"device"`	Анонимное устройство
`"session"`	Браузерная сессия
`"org"`	Организация / воркспейс

Лучшие практики

Используйте переменные окружения:

const manager = new FlipFlag({
  publicKey: process.env.FLIPFLAG_PUBLIC_KEY!,
  privateKey: process.env.FLIPFLAG_PRIVATE_KEY,
});

Инициализируйте один раз и экспортируйте:

// lib/flipflag.ts
export const manager = new FlipFlag({ /* ... */ });
await manager.init();

Завершайте корректно при остановке сервиса:

process.on("SIGTERM", () => {
  manager.destroy();
  process.exit(0);
});

Обрабатывайте ошибки инициализации:

try {
  await manager.init();
} catch (error) {
  console.error("Failed to initialize FlipFlag:", error);
}

Устранение проблем

Config file not found

Error: FlipFlag: cannot read config at /path/to/.flipflag.yml: ENOENT

Установите ignoreMissingConfig: true или создайте файл конфига.

Public key missing

Error: Public key is missing.

Параметр publicKey обязателен.

Флаги не синхронизируются

Проверьте, что передан privateKey — без него создание флагов недоступно.
Проверьте сетевой доступ к API FlipFlag.
Убедитесь в корректности ключей.

Дополнительные материалы

React SDK — хуки для работы с флагами в React
FlipFlag CLI — командная утилита для управления флагами
MCP-сервер — подключение к Claude Code, Cursor и Codex CLI

FlipFlag SDK

On this page