@flipflag/react
v2.1.0
Published
React bindings for FlipFlag SDK (works with React and Next.js)
Downloads
197
Maintainers
epolevovReadme
FlipFlag React
React bindings for FlipFlag — feature flags and remote configuration for React and Next.js applications.
Built on top of @flipflag/sdk, this package provides idiomatic React APIs:
providers, hooks, and safe client-side defaults.
Features
- React-first API (
Provider, hooks) - Works with React 18+ and Next.js (App & Pages Router)
- Safe by default for the browser (public key only)
- Automatic re-rendering on flag updates
- Optional SSR-friendly bootstrapping
- Full TypeScript support
- Zero config required on the client
Installation
npm install @flipflag/react @flipflag/sdk
# or
yarn add @flipflag/react @flipflag/sdk
reactand@flipflag/sdkare declared as peer dependencies.
Core Concepts
FlipFlagProvider
Owns a singleFlipFlagmanager instance and handles lifecycle (init, polling,destroy).Hooks (
useFlag,useFlags)
Read feature flags reactively inside components.Client-safe by default
Designed to run in the browser using a public key only.
Quick Start (React)
import { FlipFlagProvider, useFlag } from "@flipflag/react";
function NewNavbar() {
const enabled = useFlag("new-navbar", false);
return enabled ? <div>New navbar</div> : <div>Old navbar</div>;
}
export function App() {
return (
<FlipFlagProvider
options={{
publicKey: "YOUR_PUBLIC_KEY",
}}
>
<NewNavbar />
</FlipFlagProvider>
);
}Next.js (App Router)
app/providers.tsx
"use client";
import { FlipFlagProvider } from "@flipflag/react";
export function Providers({ children }: { children: React.ReactNode }) {
return (
<FlipFlagProvider
options={{
publicKey: process.env.NEXT_PUBLIC_FLIPFLAG_PUBLIC_KEY!,
ignoreMissingConfig: true
}}
>
{children}
</FlipFlagProvider>
);
}app/layout.tsx
import { Providers } from "./providers";
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html>
<body>
<Providers>{children}</Providers>
</body>
</html>
);
}Hooks API
useFlag(name, fallback?)
Returns a boolean feature flag value.
const enabled = useFlag("checkout-v2");With fallback:
const enabled = useFlag("checkout-v2", false);useFlags(names, fallback?)
Read multiple flags at once.
const flags = useFlags(["checkout-v2", "new-navbar"] as const);
flags["checkout-v2"];
flags["new-navbar"];useFlipFlagReady()
Check SDK initialization state.
const { ready, error } = useFlipFlagReady();
if (!ready) return <Spinner />;
if (error) return <ErrorState />;Provider Options
export type FlipFlagReactOptions = {
publicKey: string;
privateKey?: string; // ⚠️ server-only
apiUrl?: string;
configPath?: string;
ignoreMissingConfig?: boolean;
refreshIntervalMs?: number; // default: 10_000
initialFlags?: Record<string, boolean>;
};License
MIT License