OpenFeature provider for Cloudflare SDK | LaunchDarkly

This topic documents how to get started with the LaunchDarkly OpenFeature provider for the Cloudflare SDK.

Provider quick links

The LaunchDarkly OpenFeature providers are open source. In addition to this reference guide, we provide source, API reference documentation, and a sample application:

Resource	Location
OpenFeature Provider API documentation	Provider API docs
GitHub repository	openfeature-cloudflare-server
Sample application	Sample OpenFeature Cloudflare provider application
Published module	npm

Get started

The LaunchDarkly OpenFeature provider for the Cloudflare SDK is intended for use in multi-user Cloudflare Workers. It follows the server-side LaunchDarkly model for multi-user contexts. It is not intended for use in desktop or embedded systems applications.

The provider wraps the Cloudflare SDK, which reads flag data from a Cloudflare KV namespace that LaunchDarkly keeps up to date. Before you begin, configure the Cloudflare integration for your project.

Follow these instructions to start using the LaunchDarkly OpenFeature provider for the Cloudflare SDK in your Cloudflare Worker.

Version compatibility

The LaunchDarkly OpenFeature provider for the Cloudflare SDK is compatible with the OpenFeature Node.js SDK v1.x, version 1.16.0 and later.

The provider requires version 2.7.0 or later of the Cloudflare SDK.

Install the provider

First, install the LaunchDarkly and OpenFeature packages:

Shell

npm install @openfeature/server-sdk
npm install @launchdarkly/cloudflare-server-sdk
npm install @launchdarkly/openfeature-cloudflare-server

Then turn on the Node.js compatibility flag in your wrangler.toml. This allows the underlying Cloudflare SDK to use node:events:

wrangler.toml

compatibility_flags = [ "nodejs_compat" ]

Next, import the OpenFeature and LaunchDarkly namespaces in your application code:

LaunchDarkly Cloudflare provider

import { OpenFeature } from '@openfeature/server-sdk';
import { LaunchDarklyProvider } from '@launchdarkly/openfeature-cloudflare-server';

Initialize the provider

After you install and import the provider, create an instance of LaunchDarklyProvider and register it with OpenFeature. Specify your client-side ID and your Cloudflare KV namespace binding here. In this example, the binding is env.LD_KV. The provider only uses the client-side ID to read flag data for a particular environment from the KV namespace. It does not connect to LaunchDarkly servers.

Here’s how:

JavaScript

const provider = new LaunchDarklyProvider('example-client-side-id', env.LD_KV);
await OpenFeature.setProviderAndWait(provider);
const client = OpenFeature.getClient();

Initialize the provider once per isolate

The KV namespace binding is only available inside your Worker’s fetch handler, but OpenFeature.setProviderAndWait registers the provider on a registry that every concurrent request in the Workers isolate shares. Do not run this initialization on every request. Instead, guard it so it runs once per isolate, and reuse the provider for every subsequent request. To learn more, read Usage in the provider GitHub repository, which includes a complete example of this pattern.

The Cloudflare provider uses a client-side ID

The LaunchDarkly Cloudflare provider uses a client-side ID. Client-side IDs are specific to each project and environment. They are not secret, and you can include them in code. Do not embed a server-side SDK key into an edge application. Client-side IDs are available on the SDK keys page under Settings. To learn more about key types, read Keys.

This provider does not emit OpenFeature events

The Cloudflare SDK reads flag data from your KV namespace on each evaluation and does not maintain a connection to LaunchDarkly. As a result, the provider does not emit the OpenFeature ConfigurationChanged, Error, or Stale events. Because each request reads the latest flag data from the KV namespace, you do not need a change notification to receive up-to-date flag values. Re-evaluate the flag on the next request instead.

Construct a context

A context is a generalized way of referring to the people, services, machines, or other resources that encounter feature flags in your product. The OpenFeature specification calls these evaluation contexts.

In the LaunchDarkly provider:

Contexts always have a particular context kind. If you do not specify a kind, the provider treats the context as having a “user” kind. To specify a different kind, including a multi-context, you must include a kind attribute.
Contexts must have a targeting key. This is optional in the OpenFeature specification, but LaunchDarkly requires a key for evaluation. You can specify this using targetingKey, as in the OpenFeature specification, or key, which is the typical LaunchDarkly identifier for the targeting key.

Here are examples of a context:

const context = {
targetingKey: "example-user-key", // Could also use "key" instead of "targetingKey".
};

For additional examples, read OpenFeature specific considerations in the provider GitHub repository.

Evaluate a context

To evaluate feature flags for a context, use the OpenFeature Evaluation API. For example:

Evaluate a context

const flagValue = await client.getBooleanValue("example-flag-key", false, context);

Track metrics

To associate metrics with actions customers take in your application, use the OpenFeature Tracking API.

The Cloudflare SDK does not send events unless you enable them. To enable events, pass { sendEvents: true } as the third argument when you construct the LaunchDarklyProvider. Then, flush events inside ctx.waitUntil so they finish sending after the Worker returns its response. Because flushing only sends the events queued so far, it is safe to call on every request.

Here is an example:

Track a customer action

client.track('example-event-key', context, { "optionalCustomData": "optionalCustomValue"});
ctx.waitUntil(provider.getClient().flush());

To learn more, read track.

Access the LaunchDarkly client

You may need access to the LDClient from within the Cloudflare SDK if you are working on use cases not supported by OpenFeature, such as flushing events.

To access the LDClient, use getClient():

JavaScript

const ldClient = provider.getClient();