Bucketeer React SDK for Web Clients

This SDK enables seamless access to your feature flags in React applications using Bucketeer. It provides React hooks and components for easy integration, and is built on top of the robust @bucketeer/js-client-sdk.

Bucketeer is an open-source platform created by CyberAgent to help teams make better decisions, reduce deployment lead time and release risk through feature flags. Bucketeer offers advanced features like dark launches and staged rollouts that perform limited releases based on user attributes, devices, and other segments.

> [!WARNING]
> This is a beta version. Breaking changes may be introduced before general release.

For documentation related to flags management in Bucketeer, refer to the Bucketeer documentation website.

Features

- 🚀 React Context and Hooks for easy integration
- 🔧 TypeScript support with full type safety
- ⚡ Real-time feature flag updates
- 🎯 Multiple variation types (boolean, string, number, object)
- 🧪 User attribute management
- 📦 Tree-shakeable and lightweight

Installation

``bash
npm install @bucketeer/react-client-sdk
`

$3

React Version Support:
- ✅ Supported: React 18.2.0 and above
- ⚠️ May work: React 18.0.0 - 18.1.x (not officially supported)

> Make sure your react, react-dom, @types/react, and @types/react-dom versions all match.

Usage

$3

Initialize the Bucketeer client and provide it to your app using the BucketeerProvider:

> Use defineBKTConfigForReact to create your config and defineBKTUser to create a user and initializing the client using initializeBKTClient

`tsx
import React, { useEffect, useState } from 'react';
import {
BucketeerProvider,
defineBKTConfigForReact,
defineBKTUser,
initializeBKTClient,
getBKTClient,
destroyBKTClient,
type BKTClient,
} from '@bucketeer/react-client-sdk';

const config = defineBKTConfigForReact({
apiKey: 'your-api-key',
apiEndpoint: 'https://api.example.com',
appVersion: '1.0.0',
featureTag: 'web',
});

const user = defineBKTUser({
id: 'user-123',
customAttributes: {
platform: 'ios',
version: '1.0.0',
},
});

export default function App() {
const [client, setClient] = useState(null);
useEffect(() => {
const init = async () => {
try {
await initializeBKTClient(config, user);
} catch (error) {
if (error instanceof Error && error.name === 'TimeoutException') {
// TimeoutException but The BKTClient SDK has been initialized
console.warn('Bucketeer client initialization timed out, but client is already initialized.');
} else {
console.error('Failed to initialize Bucketeer client:', error);
return;
}
}
try {
const bktClient = getBKTClient()!;
setClient(bktClient);
} catch (error) {
console.error('Failed to initialize Bucketeer client:', error);
}
};
init();
return () => {
destroyBKTClient();
};
}, []);
if (!client) {
return

> If you see a TimeoutException error during initialization, it means the Bucketeer client has already been initialized successfully. This error is safe to ignore and does not affect the client’s functionality.

$3

`tsx
import React from 'react';
import {
useBooleanVariation,
useStringVariation,
useNumberVariation,
useObjectVariation,
useBooleanVariationDetails,
useStringVariationDetails,
useNumberVariationDetails,
useObjectVariationDetails,
} from '@bucketeer/react-client-sdk';

function MyComponent() {
// Boolean feature flag
const showNewFeature = useBooleanVariation('show-new-feature', false);
// String feature flag
const theme = useStringVariation('app-theme', 'light');
// Number feature flag
const maxItems = useNumberVariation('max-items', 10);
// JSON feature flag
const config = useObjectVariation('app-config', { timeout: 5000 });
// Feature flag with detailed evaluation information
const featureDetails = useBooleanVariationDetails('advanced-feature', false);
// Access client for advanced operations
const client = useBucketeerClient();
const handleUpdateUser = () => {
client.updateUserAttributes({
plan: 'premium',
region: 'us-west',
});
};
return (


#### BucketeerProvider

Provides Bucketeer context to child components. Most users should use the provided hooks for feature flag access; direct context access is for advanced use cases.

Props:
- client: BKTClient - Bucketeer client instance
- children: ReactNode - Child components

`tsx

{/ Your app content here /}


`

Inside your components, you can access the Bucketeer client and last updated time using the useContext hook:

`tsx
import { useContext } from 'react';
import { BucketeerContext } from '@bucketeer/react-client-sdk';
const { client, lastUpdated } = useContext(BucketeerContext);
`

$3

#### useBooleanVariation(flagId, defaultValue)

Returns a boolean feature flag value.

Parameters:
- flagId: string - The feature flag identifier
- defaultValue: boolean - Default value if flag is not available

Returns: boolean

#### useStringVariation(flagId, defaultValue)

Returns a string feature flag value.

Parameters:
- flagId: string - The feature flag identifier
- defaultValue: string - Default value if flag is not available

Returns: string

#### useNumberVariation(flagId, defaultValue)

Returns a number feature flag value.

Parameters:
- flagId: string - The feature flag identifier
- defaultValue: number - Default value if flag is not available

Returns: number

#### useObjectVariation(flagId, defaultValue)

Returns a JSON/object feature flag value with type safety. Uses the modern objectVariation API.

Parameters:
- flagId: string - The feature flag identifier
- defaultValue: T - Default value if flag is not available

Returns: T

Note: The generic type T must extend BKTValue (which includes objects, arrays, and primitive values).

#### useBooleanVariationDetails(flagId, defaultValue)

Returns a boolean feature flag value along with detailed evaluation information.

Parameters:
- flagId: string - The feature flag identifier
- defaultValue: boolean - Default value if flag is not available

Returns: BKTEvaluationDetails - Object containing:
- variationValue: boolean - The feature flag value
- featureId: string - The feature flag identifier
- featureVersion: number - Version of the feature flag
- userId: string - User ID used for evaluation
- variationId: string - ID of the variation returned
- variationName: string - Name of the variation
- reason: string - Reason for the evaluation result

#### useStringVariationDetails(flagId, defaultValue)

Returns a string feature flag value along with detailed evaluation information.

Parameters:
- flagId: string - The feature flag identifier
- defaultValue: string - Default value if flag is not available

Returns: BKTEvaluationDetails

#### useNumberVariationDetails(flagId, defaultValue)

Returns a number feature flag value along with detailed evaluation information.

Parameters:
- flagId: string - The feature flag identifier
- defaultValue: number - Default value if flag is not available

Returns: BKTEvaluationDetails

#### useObjectVariationDetails(flagId, defaultValue)

Returns a JSON/object feature flag value along with detailed evaluation information.

Parameters:
- flagId: string - The feature flag identifier
- defaultValue: T - Default value if flag is not available

Returns: BKTEvaluationDetails

Note: The generic type T must extend BKTValue.

#### useBucketeerClient()

Returns the initialized Bucketeer client instance.
Returns: BKTClient | null

`tsx
import { useBucketeerClient } from '@bucketeer/react-client-sdk';
const client = useBucketeerClient();
`

Without the hook useBucketeerClient(), you can still access the Bucketeer client using the JS SDK methods:
`tsx
import { getBKTClient } from '@bucketeer/react-client-sdk';
const client = getBKTClient();
`

Re-exported Types

The React SDK re-exports several types from the bkt-js-client-sdk for convenience. Examples include:

- BKTConfig - Bucketeer configuration object
- BKTUser - User information object
- BKTClient - Bucketeer client instance
- BKTValue - Valid feature flag value types
- BKTEvaluationDetails - Detailed evaluation information for feature flags
- defineBKTConfig - Helper to create configuration
- defineBKTUser - Helper to create user objects


For full JS API reference, see the Bucketeer documentation website.

Development

$3

`bash


Install dependencies

- pnpm build - Build the library for production
- pnpm dev - Build in watch mode
- pnpm test - Run tests
- pnpm test:watch - Run tests in watch mode
- pnpm test:coverage - Run tests with coverage report
- pnpm lint - Lint and fix code
- pnpm lint:check - Check linting without fixing
- pnpm format - Format code with Prettier
- pnpm format:check - Check formatting without fixing
- pnpm type-check - Run TypeScript type checking

$3

To see the SDK in action, you can run the included example:

- Copy the example/env_template file to example/.env and update it with your Bucketeer credentials. Example:

`env
VITE_BUCKETEER_API_KEY=your-api-key
VITE_BUCKETEER_API_ENDPOINT=https://your-bucketeer-endpoint
`

- Build the SDK
`bash
pnpm build
`

- Start the example app
`bash
pnpm example:start
``

Dependencies

This library uses the @bucketeer/js-client-sdk under the hood.

License

Apache