@spotify-confidence/integration-react

OpenFeature Web SDK React Integration

Deprecation Notice

As of 2024-04-30, the experimental integration-react library is officially deprecated. We encourage all users to transition to the official OpenFeature React SDK to ensure better support and newer features.

Why is this deprecation happening?

The integration-react project was developed as a React wrapper for OpenFeature to provide initial support for integrating feature flags into React applications. Since then, the OpenFeature team has released an official React SDK, which offers a more robust, efficient, and feature-rich solution.

What should you do?

If you are currently using integration-react, we recommend migrating to the official OpenFeature React SDK as soon as possible. This new SDK is actively maintained and supports the latest features and optimizations for feature flagging in React applications.

For detailed instructions on how to migrate and for more information about the benefits of the new SDK, please visit the official repository: 🔗 OpenFeature React SDK

This is a helper package to use OpenFeature in React and ReactNative. It is not official OpenFeature and relies on behaviour from the ConfidenceWebProvider specifically.

Usage

Enabling the provider, setting the evaluation context and resolving flags in React

setProvider makes the Provider launch a network request to initialize the flags. In cases of success the ProviderEvents.Ready event will be emitted. In cases of failure of the network request, the ProviderEvent.Error event will be emitted. The ProviderEvents events will be emitted only when we are done with the network request, either a successful or a failed network response. If the network response failed, default values will be returned on flag evaluation, if the network request is successful we update the flags and then emit ProviderEvents.Ready.

Notes:

• It's advised not to perform setContext while setProvider is running, you can await setting the context first, or listen to the ProviderEvent.Ready via a handler on OpenFeaure.

import React, { useEffect } from 'react';
import { createConfidenceWebProvider } from '@spotify-confidence/openfeature-web-provider';
import { OpenFeature, OpenFeatureAPI } from '@openfeature/web-sdk';
import { useStringValue } from '@spotify-confidence/integration-react';

const provider = createConfidenceWebProvider({
  clientSecret: 'mysecret',
  fetchImplementation: window.fetch.bind(window),
  timeout: 1000,
});

const App = () => {
  useEffect(() => {
    OpenFeature.setContext({
      targetingKey: 'myTargetingKey',
    }).then(() => {
      OpenFeature.setProvider(provider);
    });
  }, []);

  return (
    <React.Suspense fallback={<Loading />}>
      <InnerComponent />
    </React.Suspense>
  );
};

function InnerComponent() {
  const str = useStringValue('flag.some-string', 'default');

  return <p>{str}</p>;
}

Using a custom client

To use a custom client you can wrap your components in the OpenFeatureContextProvider component.

import { OpenFeatureContextProvider } from '@spotify-confidence/integration-react';

const App = () => {
  return (
    <OpenFeatureContextProvider name={'my-client-name'}>
      <React.Suspense fallback={<Loading />}>
        <InnerComponent />
      </React.Suspense>
    </OpenFeatureContextProvider>
  );
};

Notes:

• React.Suspense is used to show users a loading state whilst the flags are pending, to limit flickering experiences for users.
• If the context is changed after a render, the app will not refresh until the resolve is complete, the web page will only update once, with the new flag values.

Hooks

useStringValue

import { useStringValue } from '@spotify-confidence/integration-react';

const str: string = useStringValue('flagKey', 'default');

useStringDetails

import { useStringDetails } from '@spotify-confidence/integration-react';
import { ResolutionDetails } from '@openfeature/web-sdk';

const details: ResolutionDetails<string> = useStringDetails('flagKey', 'default');

useNumberValue

import { useNumberValue } from '@spotify-confidence/integration-react';

const num: number = useNumberValue('flagKey', 0);

useNumberDetails

import { useNumberDetails } from '@spotify-confidence/integration-react';
import { ResolutionDetails } from '@openfeature/web-sdk';

const details: ResolutionDetails<number> = useNumberDetails('flagKey', 0);

useBooleanValue

import { useBooleanValue } from '@spotify-confidence/integration-react';

const bool: boolean = useBooleanValue('flagKey', false);

useBooleanDetails

import { useBooleanDetails } from '@spotify-confidence/integration-react';
import { ResolutionDetails } from '@openfeature/web-sdk';

const details: ResolutionDetails<boolean> = useBooleanDetails('flagKey', false);

useObjectValue

import { useObjectValue } from '@spotify-confidence/integration-react';

const struct: { val: string } = useObjectValue('flagKey', { val: 'default' });

useObjectDetails

import { useObjectDetails } from '@spotify-confidence/integration-react';
import { ResolutionDetails } from '@openfeature/web-sdk';

const details: ResolutionDetails<{ val: string }> = useObjectDetails('flagKey', { val: 'default' });

Usage in Next13

Server Components

In Next13's server components using a dynamic paradigm OpenFeature sdk is recommended. This means setting up a Confidence server provider, see docs. Then you can use the async methods on an OpenFeature Client in your server component.

Client Components

There are two options for usage of OpenFeature's Clients in Next's Client Components.

1. Pass the flag value as a property from a Server Component.
2. Setup a Static Context OpenFeature Client and corresponding Confidence Web Provider.

Option #1 is very simple to implement and will work for most cases.

Option #2 is more complex and requires the OpenFeature global API to be configured in the client bundle (under a 'use client' directive), and the Confidence Web Provider, OpenFeature Context and OpenFeature's provider must be set only in the browser. This will require making a component with a client boundary and checking if you're on the sever either by using a useEffect Hook, or by checking the typeof window.

Usage in Next12

In Next12 using a dynamic paradigm OpenFeature sdk is recommended. This means setting up a Confidence server provider, see docs. Using this OpenFeature client in the getServerSideProps method to pass the retrieved flag values from the server to the client.