npm package: @flagdeck/react
Description: React components and hooks for Flagdeck feature flags
Author: Flagdeck
Latest version: 0.0.9

# 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

```bash
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:

```jsx
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:

```jsx
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:

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

### `<WithFeature />`

Render prop component for more flexible control:

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

### `<FlagValue />`

Component to access and render specific flag values:

```jsx
<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:

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

### `useFlagValue(flagKey, defaultValue)`

Hook to get the specific value of a feature flag:

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

### `useFlags(flagKeys, defaultValue)`

Hook to check multiple flags at once:

```jsx
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:

```jsx
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:

```jsx
<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](https://flagdeck.com/docs/sdks/react).

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