Flagdeck React SDK

Overview

The Flagdeck React SDK provides integration of the Flagdeck feature flag system with React applications. It allows you to easily implement feature flags, A/B testing, and targeted rollouts in your React apps.

Installation

npm install @flagdeck/react
# or
yarn add @flagdeck/react
# Using pnpm
pnpm add @flagdeck/react

Quick Start

Wrap your app with the FlagdeckProvider to start using feature flags in your components:

import React from 'react';
import { FlagdeckProvider } from '@flagdeck/react';

function App() {
  return (
    <FlagdeckProvider
      options={{
        apiKey: 'YOUR_API_KEY',
        debug: true,
        realTimeUpdates: true,
      }}
      context={{               // Targeting context for flag evaluation
        userId: 'user-123',
        attributes: {
          country: 'US',
          plan: 'premium'
        }
      }}
    >
      <YourApp />
    </FlagdeckProvider>
  );
}

Then use one of our hooks or components to check feature flags:

import { useFlag } from '@flagdeck/react';

function FeatureComponent() {
  const { isEnabled, isLoading } = useFlag('new-feature');

  if (isLoading) {
    return <div>Loading...</div>;
  }

  return (
    <div>
      {isEnabled ? (
        <p>New feature is enabled!</p>
      ) : (
        <p>New feature is disabled.</p>
      )}
    </div>
  );
}

Core Components

<FlagdeckProvider />

The root provider component to initialize the SDK and provide flag data to all child components.

Props

| Prop | Type | Description | |------|------|-------------| | options | FlagdeckOptions | Configuration options for the SDK | | context | Partial<EvaluationContext> | Targeting context for flag evaluation | | readyDelayMs | number | Optional delay before components can access flags | | children | ReactNode | React children |

<FeatureFlag />

Component for conditional rendering based on flag state:

<FeatureFlag
  flagKey="new-feature"
  fallback={<p>Feature disabled</p>}
>
  <p>Feature enabled!</p>
</FeatureFlag>

<WithFeature />

Render prop component for more flexible control:

<WithFeature flagKey="premium-dashboard">
  {({ isEnabled, isLoading }) => (
    isLoading ? (
      <div>Loading...</div>
    ) : isEnabled ? (
      <PremiumDashboard />
    ) : (
      <UpgradeBanner />
    )
  )}
</WithFeature>

<FlagValue />

Component to access and render specific flag values:

<FlagValue flagKey="theme-color" defaultValue="blue">
  {({ value, isLoading }) => (
    <div style={{ backgroundColor: value }}>
      Theme color: {value}
    </div>
  )}
</FlagValue>

Hooks

useFlag(flagKey, defaultValue)

Hook to check if a feature flag is enabled:

const { isEnabled, isLoading, error } = useFlag('new-feature', false);

useFlagValue(flagKey, defaultValue)

Hook to get the specific value of a feature flag:

const { value, isLoading, error } = useFlagValue('theme-color', 'blue');

useFlags(flagKeys, defaultValue)

Hook to check multiple flags at once:

const { values, isLoading, errors } = useFlags(['feature-a', 'feature-b'], false);
// values = { 'feature-a': true, 'feature-b': false }

useFlagdeck()

Hook to access the Flagdeck client instance and context:

const { client, isReady, error, context, setContext } = useFlagdeck();

// Update the context at runtime
setContext({
  userId: 'user-456',
  attributes: {
    plan: 'enterprise'
  }
});

Real-time Updates

The SDK supports real-time flag updates using Server-Sent Events (SSE). Enable real-time updates in the options to automatically update your UI when flag values change:

<FlagdeckProvider
  options={{
    apiKey: 'YOUR_API_KEY',
    realTimeUpdates: true,  // Enable real-time updates
  }}
  context={{
    userId: 'user-123',
    attributes: { plan: 'premium' }
  }}
>
  <YourApp />
</FlagdeckProvider>

Error Handling

All hooks and components provide error information to help with debugging and fallback scenarios.

Complete API Reference

For detailed API documentation, advanced usage examples, and all available options, please visit the official Flagdeck React SDK documentation.

The API reference includes:

• Complete options configuration for FlagdeckProvider
• All available context attributes for targeting
• Advanced flag evaluation strategies
• Error handling best practices
• TypeScript interfaces and type definitions

License

MIT