Concepts

Flagship organizes feature flags into apps. You define flags with variants and targeting rules, then evaluate them within Cloudflare's global network.

Overview

Flagship feature flags go through three stages from creation to evaluation:

1. Configure — Create flags and targeting rules in the Cloudflare dashboard ↗ or through the API.
2. Propagate — Flagship automatically distributes your flag configuration across Cloudflare's global network within seconds.
3. Evaluate — Your Worker (or SDK) evaluates flags locally using the propagated configuration. There is no round-trip to a central server.

Flag changes take effect globally within seconds of saving. You do not need to redeploy your Worker or restart your application. If the dashboard is temporarily unavailable, flag evaluation continues to work using the last propagated configuration.

Apps

An app is the top-level organizational unit in Flagship. It groups related flags together.

An app typically maps to a single project, service, or product surface. Each Cloudflare account can have multiple apps. For example, you might create one app for your marketing site and another for your API backend.

Flags

A flag is a named feature toggle. Each flag has a key, a set of variants, targeting rules, and an enabled/disabled state.

Flag keys must be unique within an app. Keys can contain letters, numbers, hyphens, and underscores.

When a flag is disabled, it always returns the default variant regardless of any targeting rules. Choose a default variant that is safe for your application if Flagship cannot evaluate the flag.

Variants

Variants are the possible values a flag can return. Each flag must have at least one variant, and one variant is designated as the default.

Flagship supports four variant types:

Type	Example
Boolean	on: true, off: false
String	v1: "old-checkout", v2: "new-checkout"
Number	low: 100, high: 1000
JSON	premium: { "tier": "premium", "features": ["analytics", "export"] }

Use boolean flags for simple on/off toggles. Use string, number, or JSON flags when you need to deliver configuration values or structured data. JSON variants can contain objects or arrays.

Targeting rules

Targeting rules control which variant a flag returns for a given request. Rules are evaluated in sequential order, and the first matching rule wins. If no rule matches, the default variant is returned.

Each rule contains:

• Conditions that compare an attribute from the evaluation context against a value using an operator.
• An optional percentage rollout that splits traffic across variants.
• A variant to serve when the rule matches.

Conditions within a rule can be grouped with AND/OR operators.

Refer to Targeting rules and Operators for the full list of operators and configuration options.

Evaluation context

The evaluation context is a set of key-value attributes that describe the current user or request (for example, userId, country, plan).

You pass the context as the third argument to evaluation methods on the binding:

TypeScript

const value = await env.FLAGS.getBooleanValue("new-checkout", false, {
  userId: "user-42",
  country: "US",
});

When using the OpenFeature SDK, you pass context through the OpenFeature evaluation context object.

Flagship uses context attributes to match targeting rules and to determine percentage rollout bucketing. A consistent context (for example, the same userId) produces the same rollout result on every evaluation.

Avoid sending sensitive data in evaluation context. Only include attributes needed by targeting rules or rollout bucketing.

Flag propagation

After you change a flag, it can take up to 30 seconds for the updated value to reflect globally. During this propagation window, some evaluations may still return the previous flag value.