@buildrflags/react

Official React SDK for BuildrFlags — feature flag evaluation via hooks and context.

Installation

npm install @buildrflags/react
# or
pnpm add @buildrflags/react
# or
yarn add @buildrflags/react

Peer dependency: React 18+ or 19+.

Quick Start

Wrap your app with <BuildrFlagsProvider> and use hooks anywhere inside:

import { BuildrFlagsProvider, useFlag } from '@buildrflags/react';

function App() {
  return (
    <BuildrFlagsProvider
      apiKey="bf_production_xxx"
      baseUrl="https://api.flags.buildrlab.com"
    >
      <MyComponent />
    </BuildrFlagsProvider>
  );
}

function MyComponent() {
  const { enabled: showSignup } = useFlag('features.signupEnabled');

  if (!showSignup) return null;
  return <SignupForm />;
}

Provider Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | apiKey | string | required | Your BuildrFlags API key (starts with bf_) | | baseUrl | string | https://api.flags.buildrlab.com | API base URL | | refreshInterval | number | 60000 (1 min) | Auto-refresh interval in ms. Set to 0 to disable | | initialFlags | Record<string, boolean> | — | Pre-loaded flags for SSG/SSR | | children | ReactNode | required | Your app tree |

Hooks

useFlag(flagKey)

Returns the evaluation result for a single flag.

const { enabled, isLoading } = useFlag('my-feature');

| Field | Type | Description | |-------|------|-------------| | enabled | boolean | Whether the flag is enabled (false if not found) | | isLoading | boolean | true until the first fetch completes |

useFlags()

Returns all flags with loading and error state.

const { flags, isLoading, error } = useFlags();

// flags is Record<string, boolean>
if (flags['dark-mode']) {
  // ...
}

useFlagValue(flagKey, defaultValue?)

Simple boolean getter. Returns defaultValue (default: false) while loading or if the flag is missing.

const showBanner = useFlagValue('ui.showBanner', true);

SSR / SSG

Pass pre-fetched flags via initialFlags to avoid a loading flash:

// In getServerSideProps / loader
const res = await fetch('https://api.flags.buildrlab.com/api/evaluate/all', {
  headers: { 'X-API-Key': process.env.BUILDRFLAGS_API_KEY! },
});
const { flags } = await res.json();
const initialFlags = Object.fromEntries(
  flags.map((f) => [f.flagKey, f.enabled])
);

// In your component
<BuildrFlagsProvider
  apiKey={process.env.NEXT_PUBLIC_BUILDRFLAGS_API_KEY!}
  initialFlags={initialFlags}
>
  <App />
</BuildrFlagsProvider>

Error Handling

• On fetch failure, useFlags() sets error and flags remain at their last known values (or empty {}).
• useFlag() returns enabled: false for unknown flags.
• useFlagValue() returns the defaultValue when the flag is missing or still loading.

License

MIT — BuildrFlags