React

Introduction

The React SDK is intended to be used by React web applications running on modern web browsers. All modern web browsers on popular platforms should be supported.

The minimum supported version of React is 16.8.0.

Browser SDKs are tested on the latest versions of Chrome, Firefox, Safari, and Edge.

Telemetry collection within browser SDKs uses Web Workers to aggregate and send telemetry data. If the SDK runs on older browsers without Web Workers support, config evaluation will continue to work but no telemetry data will be collected for that session.

Installation

The SDK can be installed from NPM: https://www.npmjs.com/package/@configdirector/react-web-sdk

npm install --save @configdirector/react-web-sdk

yarn add @configdirector/react-web-sdk

pnpm add @configdirector/react-web-sdk

bun add @configdirector/react-web-sdk

Configure and initialize the provider

Initialize the provider with your client SDK key:

import { createRoot } from "react-dom/client"
import App from "./App"
import { ConfigDirectorProvider } from "@configdirector/react-web-sdk";

createRoot(document.getElementById("root")!).render(
  <ConfigDirectorProvider sdkKey="YOUR-CLIENT-SDK-KEY">
    <App />
  </ConfigDirectorProvider>
);

Alternatively, you can initialize it with the HOC asynchronously and wait for initialization before starting your application. This can prevent the config values to flicker from the default value to the evaluated value during initialization.

An optional timeout can be provided to configure how long to await for the client to initialize before rendering the application. In the event of a timeout, the client will continue to attempt to connect in the background and config values will return the default value provided in code until a connection to ConfigDirector services is established.

import { createRoot } from "react-dom/client"
import App from "./App"
import { withProvider } from "@configdirector/react-web-sdk";

(async () => {
  const ConfigDirectorProvider = await withProvider({
    sdkKey: "YOUR-CLIENT-SDK-KEY",
    timeout: { 2_000 }, // 2,000 milliseconds timeout, defaults to 3,000
  });

  createRoot(document.getElementById('root')!).render(
    <ConfigDirectorProvider>
      <App />
    </ConfigDirectorProvider>
  );
})();

Additional configuration options

These configuration options can be passed in to the ConfigDirectorProvider or to the withProvider HOC as an object in the second argument.

context

The user context to be used during targeting rules evaluation:

import { createRoot } from "react-dom/client";
import App from "./App";
import { ConfigDirectorProvider } from "@configdirector/react-web-sdk";

createRoot(document.getElementById("root")!).render(
  <ConfigDirectorProvider
    sdkKey="YOUR-CLIENT-SDK-KEY"
    context={{ id: "12345", name: "Example User", traits: { region: "North America" } }}>
    <App />
  </ConfigDirectorProvider>,
);

logger

By default, the SDK logs to the console and it is set to log warnings and errors only. You can configure a logger by either creating a ConfigDirector console logger with a different log level, or by implementing the ConfigDirectorLogger interface to provide your own logger. The interface can be used to create an adapter to another logging library.

Configure the ConfigDirector console logger to a different level:

import { createRoot } from "react-dom/client";
import App from "./App";
import { ConfigDirectorProvider, createConsoleLogger } from "@configdirector/react-web-sdk";

createRoot(document.getElementById("root")!).render(
  <ConfigDirectorProvider sdkKey="YOUR-CLIENT-SDK-KEY" logger={createConsoleLogger("debug")}>
    <App />
  </ConfigDirectorProvider>,
);

Implement your own logger adapter:

import { createRoot } from "react-dom/client";
import App from "./App";
import { ConfigDirectorProvider, ConfigDirectorLogger } from "@configdirector/react-web-sdk";

const myLogger: ConfigDirectorLogger = {
  debug: function (message: string, ...args: any): void {
    // your specific logging library implementation here
  },
  info: function (message: string, ...args: any): void {
    // your specific logging library implementation here
  },
  warn: function (message: string, ...args: any): void {
    // your specific logging library implementation here
  },
  error: function (message: string, ...args: any): void {
    // your specific logging library implementation here
  },
};

createRoot(document.getElementById("root")!).render(
  <ConfigDirectorProvider sdkKey="YOUR-CLIENT-SDK-KEY" logger={myLogger}>
    <App />
  </ConfigDirectorProvider>,
);

appName and appVersion

These options allow you to provide your application's name and version. These values can be used in targeting rules conditionals. For example, if a certain feature should only be enabled starting with a certain version of your application.

import { createRoot } from "react-dom/client";
import App from "./App";
import { ConfigDirectorProvider } from "@configdirector/react-web-sdk";

createRoot(document.getElementById("root")!).render(
  <ConfigDirectorProvider sdkKey="YOUR-CLIENT-SDK-KEY" appName="YOUR-APP-NAME" appVersion="1.0.2">
    <App />
  </ConfigDirectorProvider>,
);

timeout

The timeout, in milliseconds, to be used in initialization and when updating the context. This is how long the withProvider HOC will wait for data from ConfigDirector services before resolving its Promise. If the timeout is reached, withProvider will return but the client will still be in an unready status and returning default values. The client will continue to attempt to connect and retrieve config values in the background.

When using the ConfigDirectorProvider, the timeout is not as relevant since initialization will happen asynchronously.

import { createRoot } from "react-dom/client"
import App from "./App"
import { withProvider } from "@configdirector/react-web-sdk";

(async () => {
  const ConfigDirectorProvider = await withProvider({
    sdkKey: "YOUR-CLIENT-SDK-KEY",
    timeout: 2_000, // 2,000 milliseconds timeout, defaults to 3,000
  });

  createRoot(document.getElementById('root')!).render(
    <ConfigDirectorProvider>
      <App />
    </ConfigDirectorProvider>
  );
})();

url

The base URL used to connect to ConfigDirector services. This should only be provided if your environment requires you to configure a proxy server in order to connect to ConfigDirector services.

Retrieve config values

Retrieve a config value with the useConfigValue hook:

import { useConfigValue } from "@configdirector/react-web-sdk";

function YourComponent() {
  const { value } = useConfigValue("my-config-key", false);

  return (<p>my-config-key: {value}</p>);
}

export default YourComponent;

You can also determine if the client is still initializing. This can be useful in the event of a slow connection where retrieving the initial config values may be slow, so rather than transition from the in-code default value to the evaluated value, you can show a loading state until the client is ready and config values are evaluated:

import { useConfigValue } from "@configdirector/react-web-sdk";

function YourComponent() {
  const { value, loading } = useConfigValue("my-config", "default value");

  if (loading) {
    return <p>Loading...</p>;
  } else {
    return <p>My config value: {value}</p>;
  }
}

export default YourComponent;

Update the user context

import { createRoot } from "react-dom/client"
import App from "./App"
import { ConfigDirectorProvider } from "@configdirector/react-web-sdk";

createRoot(document.getElementById("root")!).render(
  <ConfigDirectorProvider
    sdkKey="YOUR-CLIENT-SDK-KEY"
    context={{ id: "12345", name: "Example User", traits: { region: "North America" } }}>
    <App />
  </ConfigDirectorProvider>
);

import { useConfigValue, useContext } from "@configdirector/react-web-sdk";

function YourComponent() {
  const { value: myConfigValue } = useConfigValue("my-config", "default value");
  const { updateContext } = useContext();

  useEffect(() => {
    updateContext({
      id: "654321",
      name: "Another User",
      traits: {
        region: "Australia",
      },
    });
  }, []);

  return (<p>My config value: {myConfigValue}</p>);
}

export default YourComponent;

useClient hook

In the event that you need to have access to the underlying Javascript ConfigDirectorClient instance for more complex behaviors, you can access the instance via the useClient hook:

import { useClient } from "@configdirector/react-web-sdk";

function YourComponent() {
  const { client } = useClient();

  // Utilize the client for more involved logic

  return <p>A more complex component</p>;
}

export default YourComponent;