js-sdk-contrib/libs/providers/flagsmith-client

Flagsmith OpenFeature provider for client-side JavaScript

Flagsmith is an open-source feature flagging and remote configuration service. This provider implements the Flagsmith JavaScript SDK for client-side applications.

Installation

npm install @openfeature/flagsmith-client-provider

Make sure that the SDK version is compatible with the peerDependencies one.

Initializing the provider

The Flagsmith OpenFeature provider can be created with the same initialization options as the Flagsmith SDK.

import { FlagsmithClientProvider } from '@openfeature/flagsmith-client-provider';
import { OpenFeature } from '@openfeature/web-sdk';

const flagsmithClientProvider = new FlagsmithClientProvider({
  environmentID: 'your_client_side_environment_key',
  cacheFlags: true,
  cacheOptions: {
    skipAPI: true,
  },
});
OpenFeature.setProvider(flagsmithClientProvider);

Examples

See our examples repository for usage with various frameworks.

Usage with React Native

To use the React Native implementation of OpenFeature, install react-native-flagsmith:

npm install flagsmith react-native-flagsmith

Then, pass the flagsmith instance from react-native-flagsmith when initializing the provider:

import flagsmith from 'react-native-flagsmith';
import { FlagsmithClientProvider } from '@openfeature/flagsmith-client-provider';
import { OpenFeature } from '@openfeature/web-sdk';

const flagsmithClientProvider = new FlagsmithClientProvider({
  environmentID: 'your_client_side_environment_key',
  flagsmithInstance: flagsmith,
});
OpenFeature.setProvider(flagsmithClientProvider);

See the React Native example application for more details.

Flag targeting and dynamic evaluation

In Flagsmith, users can be identified to perform targeted flag rollouts. Traits are key-value pairs that can be used for segment-based targeting.

Flagsmith identifiers and traits make up the OpenFeature evaluation context. They correspond to OpenFeature targeting keys and context attributes respectively:

await OpenFeature.setContext({
  targetingKey: 'my-identity-id',
  traits: {
    myTraitKey: 'my-trait-value',
  },
});

To reset the identity, set the context to an empty object:

await OpenFeature.setContext({});

Resolution reasons

This provider supports the following resolution reasons:

import { StandardResolutionReasons } from '@openfeature/web-sdk';

type FlagsmithResolutionReasons =
  | typeof StandardResolutionReasons.STATIC
  | typeof StandardResolutionReasons.CACHED
  | typeof StandardResolutionReasons.DEFAULT
  | typeof StandardResolutionReasons.ERROR;

Events

This provider emits the following events:

import { ProviderEvents } from '@openfeature/web-sdk';

type FlagsmithProviderEvents =
  | typeof ProviderEvents.Ready
  | typeof ProviderEvents.Stale
  | typeof ProviderEvents.ConfigurationChanged
  | typeof ProviderEvents.Error;

Building

Run nx package providers-flagsmith-client to build the library.

Running unit tests

Run nx test providers-flagsmith-client to execute the unit tests via Jest.