OpenFeature Web Provider

Introduction

The OpenFeature Web Provider is intended to be used in combination with the OpenFeature Web SDK. All modern web browsers on popular platforms should be supported.

The ConfigDirector OpenFeature Web Provider is 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 provider 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 provider can be installed from NPM: https://www.npmjs.com/package/@configdirector/openfeature-web-provider

npm install --save @openfeature/web-sdk @configdirector/openfeature-web-provider

yarn add @openfeature/web-sdk @openfeature/core @configdirector/openfeature-web-provider

pnpm add @openfeature/web-sdk @openfeature/core @configdirector/openfeature-web-provider

bun add @openfeature/web-sdk @openfeature/core @configdirector/openfeature-web-provider

Configure and initialize the client

1. Create an instance of the provider using your client SDK key. You can retrieve a client SDK key for each environment under SDK keys in the dashboard's navigation panel.
2. Set the OpenFeature provider.
3. Get a client instance from OpenFeature.

import { OpenFeature } from "@openfeature/web-sdk";
import { ConfigDirectorProvider } from "@configdirector/openfeature-web-provider";

const provider = new ConfigDirectorProvider("YOUR-CLIENT-SDK-KEY");
await OpenFeature.setProviderAndWait(provider);
const client = OpenFeature.getClient();

Additional configuration options

Additional configuration options can be passed into the provider in the optional second argument of the constructor.

For example, the metadata can be provided like this:

import { ConfigDirectorProvider } from "@configdirector/openfeature-web-provider";

const provider = new ConfigDirectorProvider("YOUR-CLIENT-SDK-KEY", {
  metadata: {
    appName: "YOUR-APP-NAME",
    appVersion: "1.0.2",
  },
});

The provider accepts the same configuration options as the Javascript SDK client, refer to the additional configuration options section of the Javascript SDK for a full list.

Retrieve config values

To retrieve config values, use the OpenFeature client:

const booleanValue = client.getBooleanValue("my-config-key", false);

const stringValue = client.getStringValue("my-string-config-key", "Default");

For additional information regarding the OpenFeature client refer to the OpenFeature Web SDK documentation.

Update the user context

await OpenFeature.setContext({
  targetingKey: "12345", // In OpenFeature, the `targetingKey` represents the context's user ID
  name: "Example User",
  traits: {
    region: "North America", // Any arbitrary traits which can be referenced in targeting rules
  }
});

For additional information regarding the OpenFeature client refer to the OpenFeature Web SDK documentation.

Test your code

Code that reads flags through OpenFeature is tested by swapping the provider, so it never has to change for a test and nothing from ConfigDirector is involved. The OpenFeature Web SDK ships an in-memory provider for that: TypedInMemoryProvider, in @openfeature/web-sdk 1.8 and newer, which serves the values your test sets. Earlier versions ship the same provider as InMemoryProvider, now deprecated.

Each flag is a set of named variants and the defaultVariant it resolves to:

import { OpenFeature, TypedInMemoryProvider } from "@openfeature/web-sdk";

const provider = new TypedInMemoryProvider({
  "new-checkout": { variants: { on: true, off: false }, defaultVariant: "on" },
  "max-items": { variants: { default: 20 }, defaultVariant: "default" },
});

afterEach(() => OpenFeature.close());

test("shows the new checkout", async () => {
  await OpenFeature.setProviderAndWait(provider);
  const client = OpenFeature.getClient();

  expect(client.getBooleanValue("new-checkout", false)).toBe(true);
  expect(client.getNumberValue("max-items", 0)).toBe(20);

  await provider.putConfiguration({
    "new-checkout": { variants: { on: true, off: false }, defaultVariant: "off" },
  });
  expect(client.getBooleanValue("new-checkout", true)).toBe(false);
});

putConfiguration replaces every flag and emits ConfigurationChanged with the keys it was given, so a component that re-reads its flags on that event follows the change. A flag can also carry a contextEvaluator, a function from the evaluation context to the name of the variant to serve, for a test of code that targets specific users. OpenFeature is one global, so shut it down after each test with OpenFeature.close(), which lets the next test register its own provider.

A React application that reads flags through @openfeature/react-sdk has OpenFeatureTestProvider from that package as well, a component that serves the values it is given to the hooks beneath it.