npm package: @flagbox/react
Description: FlagBox SDK for React
Author: FlagBox
Latest version: 0.0.9

# FlagBox React SDK

A React SDK for managing feature flags with FlagBox. This SDK provides a simple way to integrate feature flags into your React application.

## Installation

```bash
  npm install @flagbox/react
```
or
```bash
  yarn add @flagbox/react
```

## Basic Usage

Wrap your application with the `FlagBoxProvider` and use the `useFeatureFlag` hook to access feature flags:

```tsx
import { FlagBoxProvider, useFeatureFlag } from '@flagbox/react';

// Example component using a feature flag
function FeatureComponent() {
  const isFeatureEnabled = useFeatureFlag('my-feature', false);
  
  if (!isFeatureEnabled) {
    return null;
  }
  
  return <div>Feature is enabled!</div>;
}

// In your app root
function App() {
  const getConfig = async () => {
    // Fetch your configuration from your backend or secure storage
    const response = await fetch('/api/flagbox-config');
    return response.json();
  };

  return (
    <FlagBoxProvider getConfig={getConfig}>
      <FeatureComponent />
    </FlagBoxProvider>
  );
}
```

## Configuration

The `FlagBoxProvider` accepts the following props:

```tsx
interface FlagBoxProviderProps {
  getConfig: () => Promise<{
    apiUrl: string;
    apiKey: string;
  }>;
  children: ReactNode;
  deferRendering?: boolean;
  loadingComponent?: ReactNode;
}
```

### Props

- `getConfig`: An async function that returns the FlagBox configuration
  - `apiUrl`: The URL of your FlagBox API
  - `apiKey`: Your FlagBox API key
- `deferRendering`: (Optional) If true, children won't render until configuration is loaded
- `loadingComponent`: (Optional) Component to show while configuration is loading

### Deferred Rendering

You can choose to defer rendering of your application until the configuration is loaded:

```tsx
function App() {
  return (
    <FlagBoxProvider 
      getConfig={getConfig}
      deferRendering={true}
      loadingComponent={<div>Loading feature flags...</div>}
    >
      <YourApp />
    </FlagBoxProvider>
  );
}
```

## Using Feature Flags

The `useFeatureFlag` hook provides access to feature flags:

```tsx
function useFeatureFlag<T>(flagKey: string, defaultValue: T): T
```

### Parameters

- `flagKey`: The key of the feature flag to check
- `defaultValue`: The default value to use if the flag is not available

### Example

```tsx
function MyComponent() {
  // Boolean flag
  const isNewFeatureEnabled = useFeatureFlag('new-feature', false);
  
  // String flag
  const theme = useFeatureFlag('theme', 'light');
  
  // Number flag
  const maxItems = useFeatureFlag('max-items', 10);
  
  return (
    <div>
      {isNewFeatureEnabled && <NewFeature />}
      <div className={`theme-${theme}`}>
        {/* ... */}
      </div>
      {items.slice(0, maxItems).map(item => (
        <Item key={item.id} {...item} />
      ))}
    </div>
  );
}
```

## Error Handling

The SDK handles various error cases:

- If the configuration fails to load, the error will be available in the context
- If a flag request fails, it will fall back to the default value
- Network errors are logged to the console

## Best Practices

1. **Configuration Loading**
   - Use `deferRendering` when you need to ensure flags are available before rendering
   - Provide a meaningful loading component for better UX

2. **Default Values**
   - Always provide sensible default values for your flags
   - Consider the impact of the default value on your application

3. **Error Handling**
   - Handle cases where flags might not be available
   - Use default values that make sense for your application

4. **Performance**
   - The SDK caches flag values to minimize API calls
   - Use boolean flags for simple feature toggles
   - Use string/number flags for configuration values

## TypeScript Support

The SDK is written in TypeScript and provides full type support:

```tsx
// Type-safe flag usage
const isEnabled = useFeatureFlag<boolean>('my-feature', false);
const theme = useFeatureFlag<'light' | 'dark'>('theme', 'light');
```

## License

MIT