Flagship Rollout
Evaluate Cloudflare Flagship feature flags at the edge - progressive delivery and rollout checks in a Worker
Evaluate Cloudflare Flagship feature flags at the edge via a Workers binding. Returns boolean values or detailed evaluation metadata for targeting experiments.
API Reference
GET /flags/:key
Evaluate a boolean flag.
key string (required, path)
Flag key.
userId string (optional)
Targeting context attribute.
default string (optional)
Fallback boolean as true or false (default false).
Example Request
curl "https://your-worker.workers.dev/flags/new-checkout?userId=user-42&default=false"Success Response
{
"flagKey": "new-checkout",
"value": true,
"context": { "userId": "user-42" }
}GET /flags/:key/details
Same query params. Returns evaluation details (variant, reason, errorCode, etc.).
Example Request
curl "https://your-worker.workers.dev/flags/new-checkout/details?userId=user-42"Error Codes
400- Missing or invalid flag key (INVALID_FLAG_KEY)502- Flag evaluation failure (FLAG_ERROR)
Use Cases
- Learn Flagship Workers bindings and targeting context
- Gate features by user id at the edge
- Inspect evaluation reason / variant for debugging rollouts
- Prototype A/B or percentage rollouts before wiring into an app
Limitations
- Requires a real Flagship
app_idinwrangler.json - Demo evaluates boolean flags only
- Local
wrangler devtalks to the live Flagship app for thatapp_id - No dashboard UI in this Worker - evaluation API only
Use in your project
Copy these files into an existing Worker. Prefer Deployment to try the full experiment first. Source: apps/experiments/flagship-rollout.
import { FLAG_KEY_PATTERN } from "../constants/defaults";import type { Flagship, FlagshipEvaluationContext } from "../types/env";import type { FlagDetailsResponse, FlagValueResponse } from "../types/flags";export function validateFlagKey(input: string | undefined): string | null { if (!input || typeof input !== "string") return null; const trimmed = input.trim(); if (!FLAG_KEY_PATTERN.test(trimmed)) return null; return trimmed;}export function parseDefaultBoolean(input: string | undefined): boolean { if (input === undefined || input === null || input === "") return false; const normalized = input.trim().toLowerCase(); return normalized === "true" || normalized === "1" || normalized === "yes";}export function buildContext(userId: string | undefined): FlagshipEvaluationContext { if (!userId || !userId.trim()) return {}; return { userId: userId.trim() };}export async function evaluateBooleanFlag( flags: Flagship, flagKey: string, defaultValue: boolean, context: FlagshipEvaluationContext): Promise<FlagValueResponse> { const value = await flags.getBooleanValue(flagKey, defaultValue, context); return { flagKey, value, context };}export async function evaluateBooleanFlagDetails( flags: Flagship, flagKey: string, defaultValue: boolean, context: FlagshipEvaluationContext): Promise<FlagDetailsResponse> { const details = await flags.getBooleanDetails(flagKey, defaultValue, context); return { ...details, context };}Deployment
Configure Flagship
Create a Flagship app in the Cloudflare dashboard and set app_id on the FLAGS binding in wrangler.json.
Test your deployment
curl "https://your-worker.workers.dev/flags/new-checkout?userId=user-42"Local Development
cd apps/experiments/flagship-rollout
npm install
npm run devcurl "http://localhost:8787/flags/new-checkout?userId=user-42&default=false"Configuration
wrangler.json declares:
- Flagship binding
FLAGSwithapp_id