FlipFlag React

React‑пакет @flipflag/react предоставляет удобный API для работы с feature flags в React и Next.js приложениях. Он построен поверх базового SDK @flipflag/sdk и обеспечивает реактивный доступ к флагам, безопасную клиентскую работу и поддержку SSR.

Установка

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

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

import { FlipFlagProvider, useFlag } from "@flipflag/react";

function NewNavbar() {
  const enabled = useFlag("new-navbar", false);
  return enabled ? <div>Новая навигация</div> : <div>Старая навигация</div>;
}

export function App() {
  return (
    <FlipFlagProvider
      options={{
        publicKey: "YOUR_PUBLIC_KEY",
      }}
    >
      <NewNavbar />
    </FlipFlagProvider>
  );
}

FlipFlagProvider

FlipFlagProvider инициализирует SDK и предоставляет доступ к feature flags через React Context.

Основные опции

publicKey — публичный ключ (обязателен для клиента)
privateKey — приватный ключ (⚠️ только сервер)
apiUrl — кастомный URL API
refreshIntervalMs — интервал авто‑обновления
initialFlags — начальные значения флагов

Хуки

useFlag

const enabled = useFlag("checkout-v2", false);

Возвращает текущее значение флага или fallback.

useFlags

const flags = useFlags(["checkout-v2", "new-navbar"] as const);

Возвращает объект с несколькими флагами.

useFlipFlagReady

const { ready, error } = useFlipFlagReady();

Позволяет определить момент инициализации SDK.

Next.js (App Router)

Рекомендуется выносить провайдер в client‑component:

"use client";
import { FlipFlagProvider } from "@flipflag/react";

export function Providers({ children }) {
  return (
    <FlipFlagProvider
      options={{
        publicKey: process.env.NEXT_PUBLIC_FLIPFLAG_PUBLIC_KEY!,
      }}
    >
      {children}
    </FlipFlagProvider>
  );
}

Безопасность

Для клиентских приложений используйте только publicKey. ⚠️ Приватный ключ (privateKey) предоставляет расширенные права и не должен использоваться в браузере или мобильных приложениях.

SSR и серверный рендеринг

Пакет @flipflag/react поддерживает серверный рендеринг через отдельный экспорт @flipflag/react/server.

Серверный экспорт

import { FlipFlagHydration, getFlags } from "@flipflag/react/server";

FlipFlagHydration

Компонент для сериализации флагов на сервере. Рендерит <script> тег с JSON-данными, которые клиент автоматически подхватит при гидратации.

import { FlipFlagHydration } from "@flipflag/react/server";

// В серверном компоненте
<FlipFlagHydration flags={{ darkMode: true, newFeature: false }} />

getFlags

Хелпер для получения нескольких флагов из инициализированного SDK:

import { FlipFlag } from "@flipflag/sdk";
import { getFlags } from "@flipflag/react/server";

const sdk = new FlipFlag({ publicKey: "...", privateKey: "..." });
await sdk.init();

const flags = getFlags(sdk, ["darkMode", "newFeature"]);
// { darkMode: true, newFeature: false }

Автоматическая гидратация

FlipFlagProvider автоматически читает данные из тега <script id="__FLIPFLAG_DATA__">, если он присутствует на странице. Никакой дополнительной конфигурации не требуется.

Приоритет источников данных:

initialFlags (явно переданные через props)
__FLIPFLAG_DATA__ (автоматически из script тега)
Пустой объект + загрузка с сервера

Полный пример Next.js App Router

Серверный layout (app/layout.tsx):

import { FlipFlag } from "@flipflag/sdk";
import { FlipFlagHydration, getFlags } from "@flipflag/react/server";
import { Providers } from "./providers";

export default async function RootLayout({ children }) {
  const sdk = new FlipFlag({
    publicKey: process.env.FLIPFLAG_PUBLIC_KEY!,
    privateKey: process.env.FLIPFLAG_PRIVATE_KEY!,
  });
  await sdk.init();

  const flags = getFlags(sdk, ["darkMode", "newFeature", "betaAccess"]);

  return (
    <html>
      <body>
        <FlipFlagHydration flags={flags} />
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

Клиентский провайдер (app/providers.tsx):

"use client";
import { FlipFlagProvider } from "@flipflag/react";

export function Providers({ children }) {
  return (
    <FlipFlagProvider
      options={{
        publicKey: process.env.NEXT_PUBLIC_FLIPFLAG_PUBLIC_KEY!,
      }}
    >
      {children}
    </FlipFlagProvider>
  );
}

Клиент автоматически подхватит флаги из FlipFlagHydration без мерцания или дополнительных запросов.

Использование существующего экземпляра SDK

Если вам нужно обернуть SDK (например, для persistence), используйте опцию instance:

import { FlipFlag } from "@flipflag/sdk";
import { withLocalStorage } from "@flipflag/persist";
import { FlipFlagProvider } from "@flipflag/react";

const sdk = new FlipFlag({ publicKey: "..." });
const persistedSdk = withLocalStorage(sdk);

<FlipFlagProvider options={{ instance: persistedSdk }}>
  {children}
</FlipFlagProvider>

При использовании instance параметры SDK (publicKey, privateKey и т.д.) не требуются.

FlipFlag React

On this page