Skip to main content

OpenFeature React SDK

SpecificationRelease
codecovNPM Download

🧪 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:

Quick start​

Requirements​

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

Install​

npm​

npm install --save @openfeature/react-sdk

yarn​

# yarn requires manual installation of the peer dependencies (see below)
yarn add @openfeature/react-sdk @openfeature/web-sdk @openfeature/core

Required peer dependencies​

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

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

Usage​

The OpenFeatureProvider represents a scope for feature flag evaluations within a React application. It binds an OpenFeature client to all evaluations within child components, and allows the use of evaluation hooks. The example below shows how to use the OpenFeatureProvider with OpenFeature's InMemoryProvider.

import { EvaluationContext, OpenFeatureProvider, useFlag, 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'
    }
  },
};

// Instantiate and set our provider (be sure this only happens once)!
// Note: there's no need to await its initialization, the React SDK handles re-rendering and suspense for you!
OpenFeature.setProvider(new InMemoryProvider(flagConfig));

// Enclose your content in the configured provider
function App() {
  return (
    <OpenFeatureProvider>
      <Page></Page>
    </OpenFeatureProvider>
  );
}

function Page() {
  // Use the "query-style" flag evaluation hook.
  const { value: showNewMessage } = useFlag('new-message', true);
  return (
    <div className="App">
      <header className="App-header">
        {showNewMessage ? <p>Welcome to this OpenFeature-enabled React app!</p> : <p>Welcome to this React app.</p>}
      </header>
    </div>
  )
}

export default App;

You can use the strongly-typed flag value and flag evaluation detail hooks as well, if you prefer.

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

// boolean flag evaluation
const value = useBooleanFlagValue('new-message', false);
import { useBooleanFlagDetails } from '@openfeature/react-sdk';

// "detailed" boolean flag evaluation
const {
  value,
  variant,
  reason,
  flagMetadata
} = useBooleanFlagDetails('new-message', false);

Multiple Providers and Domains​

Multiple providers can be used by passing a domain to the OpenFeatureProvider:

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

This is analogous to:

OpenFeature.getClient('my-domain');

For more information about domains, refer to the web SDK.

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 showNewMessage = 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 showNewMessage = 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 showNewMessage = useBooleanFlagValue('new-message', false);

  return (
    <>
      {showNewMessage ? (
        <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​