Skip to content

TypeScript Server SDK

Last updated View as MarkdownAgent setup

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.

Setup

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",
});

Configuration options

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.

Local evaluation

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.

Response caching

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.

Evaluation context

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"],
});

Available hooks

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());

Migrate from another provider

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>",
	}),
);

Was this helpful?