Bucketeer - OpenFeature JS provider for a web clients

This is the official JS OpenFeature provider for accessing your feature flags with Bucketeer.

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.

In conjunction with the OpenFeature SDK you will be able to evaluate your feature flags in your web applications.

[!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.

Installation

npm install @bucketeer/openfeature-js-client-sdk

This will automatically install the required peer dependencies: @openfeature/web-sdk and @bucketeer/js-client-sdk.

Usage

Initialize the provider

Bucketeer provider needs to be created and then set in the global OpenFeatureAPI.

import { OpenFeature } from '@openfeature/web-sdk';
import { defineBKTConfig } from '@bucketeer/js-client-sdk'
import { BucketeerProvider } from '@bucketeer/openfeature-js-client-sdk';

const config = defineBKTConfig({
  apiEndpoint: 'BUCKETEER_API_ENDPOINT',
  apiKey: 'BUCKETEER_API_KEY',
  featureTag: 'FEATURE_TAG',
  appVersion: '1.2.3',
  fetch: window.fetch,
})

const initEvaluationContext = {
  targetingKey: 'USER_ID',
  app_version: '1.2.3',
}
await OpenFeature.setContext(initEvaluationContext)
await OpenFeature.setProviderAndWait(new BucketeerProvider(config))

See our documentation for more SDK configuration.

The evaluation context allows the client to specify contextual data that Bucketeer uses to evaluate the feature flags.

The targetingKey is the user ID (Unique ID) and cannot be empty.

Update the Evaluation Context

You can update the evaluation context with the new attributes if the user attributes change.

const newEvaluationContext = {
  targetingKey: 'USER_ID',
  app_version: '2.0.0',
  age: 25,
  country: 'US',
}
await OpenFeature.setContext(newEvaluationContext)

[!WARNING] Changing the targetingKey is not supported in the current implementation of the BucketeerProvider.

To change the user ID, the BucketeerProvider must be removed and reinitialized.

await OpenFeature.clearProviders()
await OpenFeature.clearContext()

// Reinitialize the provider with new targetingKey
const newEvaluationContext = {
  targetingKey: 'USER_ID_NEW',
  app_version: '2.0.0',
  age: 25,
  country: 'US',
}

const config = defineBKTConfig({
  apiEndpoint: 'BUCKETEER_API_ENDPOINT',
  apiKey: 'BUCKETEER_API_KEY',
  featureTag: 'FEATURE_TAG',
  appVersion: '1.2.3',
  fetch: window.fetch,
})

await OpenFeature.setContext(newEvaluationContext)
await OpenFeature.setProviderAndWait(new BucketeerProvider(config))

Evaluate a feature flag

After the provider is set and the provider's status is ClientProviderEvents.Ready, you can evaluate a feature flag using OpenFeatureAPI.

const client = OpenFeature.getClient();

// boolean flag
const flagValue = client.getBooleanValue('my-feature-flag', false);

// string flag
const flagValue = client.getStringValue('my-feature-flag', 'default-value');

// number flag
const flagValue = client.getNumberValue('my-feature-flag', 0);

// object flag
const flagValue = client.getObjectValue('my-feature-flag', {});

Contributing

We would ❤️ for you to contribute to Bucketeer and help improve it! Anyone can use and enjoy it!

Please follow our contribution guide here.

Development

Environment

• pnpm
  • enable it via corepack enable
• Node.js
  • check ./.node-version

You need .env file to provide api secrets. Just copy env.template and rename it to .env, then update it with your secrets.

License

Apache License 2.0, see LICENSE.