README.md

OpenFeature React SDK

OpenFeature is an open specification that provides a vendor-agnostic, community-driven API for feature flagging that works with your favorite feature flag management tool or in-house solution.

🧪 This SDK is experimental.

Overview

The OpenFeature React SDK adds React-specific functionality to the OpenFeature Web SDK.

In addition to the feature provided by the web sdk, capabilities include:

• Multiple Providers and Scoping
• Re-rendering with Context Changes
• Re-rendering with Flag Configuration Changes
• Suspense Support

🚀 Quick start

Requirements

• ES2022-compatible web browser (Chrome, Edge, Firefox, etc)
• React version 16.8+

Install

npm

npm install --save @openfeature/react-sdk

Required peer dependencies

The following list contains the peer dependencies of @openfeature/react-sdk with its expected and compatible versions:

• @openfeature/web-sdk: >=0.4.10
• react: >=16.8.0

Usage

The example below shows how to use the OpenFeatureProvider with OpenFeature's InMemoryProvider.

import { EvaluationContext, OpenFeatureProvider, useBooleanFlagValue, useBooleanFlagDetails, OpenFeature, InMemoryProvider } from '@openfeature/react-sdk';

const flagConfig = {
  'new-message': {
    disabled: false,
    variants: {
      on: true,
      off: false,
    },
    defaultVariant: "on",
    contextEvaluator: (context: EvaluationContext) => {
      if (context.silly) {
        return 'on';
      }
      return 'off'
    }
  },
};

OpenFeature.setProvider(new InMemoryProvider(flagConfig));

function App() {
  return (
    <OpenFeatureProvider>
      <Page></Page>
    </OpenFeatureProvider>
  );
}

function Page() {
  const newMessage = useBooleanFlagValue('new-message', false);
  return (
    <div className="App">
      <header className="App-header">
        {newMessage ? <p>Welcome to this OpenFeature-enabled React app!</p> : <p>Welcome to this React app.</p>}
      </header>
    </div>
  )
}

export default App;

You use the detailed flag evaluation hooks to evaluate the flag and get additional information about the flag and the evaluation.

import { useBooleanFlagDetails } from '@openfeature/react-sdk';

const {
  value,
  variant,
  reason,
  flagMetadata
} = useBooleanFlagDetails('new-message', false);

Multiple Providers and Scoping

Multiple providers and scoped clients can be configured by passing a clientName to the OpenFeatureProvider:

// Flags within this scope will use the a client/provider associated with `myClient`,
function App() {
  return (
    <OpenFeatureProvider clientName={'myClient'}>
      <Page></Page>
    </OpenFeatureProvider>
  );
}

This is analogous to:

OpenFeature.getClient('myClient');

Re-rendering with Context Changes

By default, if the OpenFeature evaluation context is modified, components will be re-rendered. This is useful in cases where flag values are dependant on user-attributes or other application state (user logged in, items in card, etc). You can disable this feature in the hook options:

function Page() {
  const newMessage = useBooleanFlagValue('new-message', false, { updateOnContextChanged: false });
  return (
    <MyComponents></MyComponents>
  )
}

For more information about how evaluation context works in the React SDK, see the documentation on OpenFeature's static context SDK paradigm.

Re-rendering with Flag Configuration Changes

By default, if the underlying provider emits a ConfigurationChanged event, components will be re-rendered. This is useful if you want your UI to immediately reflect changes in the backend flag configuration. You can disable this feature in the hook options:

function Page() {
  const newMessage = useBooleanFlagValue('new-message', false, { updateOnConfigurationChanged: false });
  return (
    <MyComponents></MyComponents>
  )
}

Note that if your provider doesn't support updates, this configuration has no impact.

Suspense Support

Frequently, providers need to perform some initial startup tasks. It may be desireable not to display components with feature flags until this is complete. Built-in suspense support makes this easy:

function Content() {
  // cause the "fallback" to be displayed if the component uses feature flags and the provider is not ready
  return (
    <Suspense fallback={<Fallback />}>
      <Message />
    </Suspense>
  );
}

function Message() {
  // component to render after READY.
  const newMessage = useBooleanFlagValue('new-message', false);

  return (
    <>
      {newMessage ? (
        <p>Welcome to this OpenFeature-enabled React app!</p>
      ) : (
        <p>Welcome to this plain old React app!</p>
      )}
    </>
  );
}

function Fallback() {
  // component to render before READY.
  return <p>Waiting for provider to be ready...</p>;
}

Resources

• Example repo