The FlagshipServerProvider implements the OpenFeature server provider interface. The provider works in Cloudflare Workers, Node.js, and any server-side JavaScript runtime that supports the Fetch API.
Inside a Cloudflare Worker, you can pass the Flagship binding directly to the provider. This avoids HTTP overhead and is the recommended approach. Outside of Workers, initialize the provider with an app ID and account ID.
Pass the Flagship binding directly to the provider. This is the recommended approach inside a Worker.
import { OpenFeature } from "@openfeature/server-sdk";
import { FlagshipServerProvider } from "@cloudflare/flagship/server";
export default {
async fetch(request, env) {
await OpenFeature.setProviderAndWait(
new FlagshipServerProvider({ binding: env.FLAGS }),
);
const client = OpenFeature.getClient();
const showNewCheckout = await client.getBooleanValue(
"new-checkout",
false,
{ targetingKey: "user-42", plan: "enterprise" },
);
if (showNewCheckout) {
return new Response("New checkout enabled!");
}
return new Response("Standard checkout.");
},
};import { OpenFeature } from "@openfeature/server-sdk";
import { FlagshipServerProvider } from "@cloudflare/flagship/server";
export default {
async fetch(request: Request, env: Env): Promise<Response> {
await OpenFeature.setProviderAndWait(
new FlagshipServerProvider({ binding: env.FLAGS }),
);
const client = OpenFeature.getClient();
const showNewCheckout = await client.getBooleanValue(
"new-checkout",
false,
{ targetingKey: "user-42", plan: "enterprise" },
);
if (showNewCheckout) {
return new Response("New checkout enabled!");
}
return new Response("Standard checkout.");
},
};Use an app ID, account ID, and an API token when running outside of a Worker (for example, in Node.js). Generate an API token from your Cloudflare account with Flagship Evaluate or Flagship App Evaluate permission.
import { OpenFeature } from "@openfeature/server-sdk";
import { FlagshipServerProvider } from "@cloudflare/flagship/server";
await OpenFeature.setProviderAndWait(
new FlagshipServerProvider({
appId: "<APP_ID>",
accountId: "<ACCOUNT_ID>",
authToken: "<API_TOKEN>",
}),
);
const client = OpenFeature.getClient();
const showNewCheckout = await client.getBooleanValue("new-checkout", false, {
targetingKey: "user-42",
plan: "enterprise",
});import { OpenFeature } from "@openfeature/server-sdk";
import { FlagshipServerProvider } from "@cloudflare/flagship/server";
await OpenFeature.setProviderAndWait(
new FlagshipServerProvider({
appId: "<APP_ID>",
accountId: "<ACCOUNT_ID>",
authToken: "<API_TOKEN>",
}),
);
const client = OpenFeature.getClient();
const showNewCheckout = await client.getBooleanValue("new-checkout", false, {
targetingKey: "user-42",
plan: "enterprise",
});| Option | Type | Required | Description |
|---|---|---|---|
binding |
Flagship |
No | The Flagship binding from env.FLAGS. Use this inside a Worker for best performance. The binding handles authentication automatically. |
appId |
string |
No | The Flagship app ID from the Cloudflare dashboard. Required when not using a binding. |
accountId |
string |
No | Your Cloudflare account ID. Required when using appId. |
authToken |
string |
No | A Cloudflare API token with Flagship Evaluate or Flagship App Evaluate permission. Required when not using a binding. |
fetchOptions |
RequestInit |
No | Custom fetch options applied to HTTP requests. |
timeout |
number |
No | Request timeout in milliseconds. Defaults to 5000. |
retries |
number |
No | Retry attempts on transient errors. Defaults to 1 and is capped at 10. |
retryDelay |
number |
No | Delay between retries in milliseconds. Defaults to 1000 and is capped at 30000. |
cacheTtl |
number |
No | Cache TTL in milliseconds. Enables response caching when greater than 0. |
cacheMaxSize |
number |
No | Maximum cached entries. Defaults to 1000 when cacheTtl is set. |
localEvaluation |
boolean |
No | Downloads flag definitions and evaluates flags in-process. Requires accountId and either appId or endpoint. Defaults to false. |
refreshInterval |
number |
No | Minimum time between local evaluation refreshes in milliseconds. Defaults to 30000. |
Provide either binding or appId, accountId, and authToken.
With local evaluation, the provider downloads the app's flag definitions and evaluates flags in-process. No network request is made per evaluation. Local evaluation works in Node.js, in Workers without a binding, and in other runtimes that support the Fetch API. It cannot be combined with a binding.
Local evaluation requires an API token with Flagship Read or Flagship App Read permission. Local evaluations do not appear in Flagship analytics.
await OpenFeature.setProviderAndWait(
new FlagshipServerProvider({
appId: "<APP_ID>",
accountId: "<ACCOUNT_ID>",
authToken: "<READ_API_TOKEN>",
localEvaluation: true,
refreshInterval: 30_000,
}),
);await OpenFeature.setProviderAndWait(
new FlagshipServerProvider({
appId: "<APP_ID>",
accountId: "<ACCOUNT_ID>",
authToken: "<READ_API_TOKEN>",
localEvaluation: true,
refreshInterval: 30_000,
}),
);The provider downloads the definitions when OpenFeature initializes it. If the first download fails, initialization fails and the provider reports the ERROR status. A 401 or 403 response reports FATAL.
The provider refreshes definitions lazily. When an evaluation runs and the downloaded definitions are older than refreshInterval, the provider starts a refresh in the background and evaluates against the current definitions. If a refresh fails, the provider keeps serving the last downloaded definitions and emits the PROVIDER_STALE event. It emits PROVIDER_READY again when a refresh succeeds.
accountId is always required. If you set endpoint instead of appId, the URL path must end in /evaluate so the provider can derive the definitions URL. Local evaluation cannot be combined with cacheTtl or binding.
Server-side response caching is off by default. Enable it with cacheTtl when you want repeated evaluations for the same flag, type, and evaluation context to reuse a recent result.
new FlagshipServerProvider({
appId: "<APP_ID>",
accountId: "<ACCOUNT_ID>",
authToken: "<API_TOKEN>",
cacheTtl: 30_000,
cacheMaxSize: 1000,
});Use caching for high-traffic server applications that repeatedly evaluate the same flags for the same contexts. Cached values may be stale until the TTL expires, so keep the TTL short for flags that you expect to change during active rollouts. The provider does not cache disabled flags or errors.
OpenFeature uses an evaluation context to pass user attributes to the flag provider. The targetingKey field is the primary user identifier.
Pass additional attributes alongside targetingKey to match targeting rules. For example, you can include plan, country, or any custom attribute your rules reference.
From version 0.6.0, the provider accepts strings, finite numbers, booleans, null, nested objects, and arrays. It normalizes valid Date values to ISO 8601 strings, including within objects and arrays. Structured context works with both binding and HTTP evaluation.
For HTTP evaluation, the provider uses POST with a JSON body when context includes objects, arrays, or null. Otherwise, it uses GET query parameters. Unsupported values, non-finite numbers, invalid dates, and cycles produce INVALID_CONTEXT errors.
const value = await client.getBooleanValue("new-checkout", false, {
targetingKey: "user-42",
profile: { plan: "enterprise" },
tags: ["beta"],
});const value = await client.getBooleanValue("new-checkout", false, {
targetingKey: "user-42",
profile: { plan: "enterprise" },
tags: ["beta"],
});The SDK ships with two hooks that you can attach to the OpenFeature client.
- LoggingHook — Logs structured information for every evaluation.
- TelemetryHook — Captures timing and event data for observability.
import { LoggingHook, TelemetryHook } from "@cloudflare/flagship/server";
OpenFeature.addHooks(new LoggingHook(), new TelemetryHook());import { LoggingHook, TelemetryHook } from "@cloudflare/flagship/server";
OpenFeature.addHooks(new LoggingHook(), new TelemetryHook());If you use another OpenFeature-compatible provider (for example, LaunchDarkly or Flagsmith), switch to Flagship by replacing the provider initialization. No changes are needed at evaluation call sites.
// Before
await OpenFeature.setProviderAndWait(
new LaunchDarklyProvider({ sdkKey: "..." }),
);
// After
await OpenFeature.setProviderAndWait(
new FlagshipServerProvider({
appId: "<APP_ID>",
accountId: "<ACCOUNT_ID>",
authToken: "<API_TOKEN>",
}),
);// Before
await OpenFeature.setProviderAndWait(
new LaunchDarklyProvider({ sdkKey: "..." }),
);
// After
await OpenFeature.setProviderAndWait(
new FlagshipServerProvider({
appId: "<APP_ID>",
accountId: "<ACCOUNT_ID>",
authToken: "<API_TOKEN>",
}),
);