Cloudflare.Flagship reference

App

Source: src/Cloudflare/Flagship/App.ts

A Cloudflare Flagship app — a container for feature flags.

Flagship is Cloudflare’s feature flag service. Flags are organized into apps that map to your projects or services; the app’s appId is what a Worker’s Flagship binding points at and what every evaluation call is scoped to. The name is mutable in place; the app id never changes.

App: Creating an App

App with a generated name

const app = yield* Cloudflare.Flagship.App("Flags", {});

App with an explicit name

const app = yield* Cloudflare.Flagship.App("Flags", {
  name: "my-service-flags",
});

App: Using the App

const app = yield* Cloudflare.Flagship.App("Flags", {});

const flag = yield* Cloudflare.Flagship.Flag("NewCheckout", {
  appId: app.appId,
  key: "new-checkout",
  defaultVariation: "off",
  variations: { off: false, on: true },
});

App: Binding to a Worker

Effect-style Worker (recommended)

Cloudflare.Flagship.ReadFlags(app) attaches the binding to the surrounding Worker and returns the runtime client for evaluating flags. Every Flagship method is mirrored as an Effect, so no Effect.tryPromise wrapping is needed.

export const App = Cloudflare.Flagship.App("Flags", {});

Cloudflare.Worker(
  "FlagsWorker",
  { main: import.meta.url },
  Effect.gen(function* () {
    const flags = yield* Cloudflare.Flagship.ReadFlags(App);
    return {
      fetch: Effect.gen(function* () {
        const enabled = yield* flags.getBooleanValue("new-checkout", false, {
          userId: "user-42",
        });
        return HttpServerResponse.text(enabled ? "on" : "off");
      }),
    };
  }).pipe(Effect.provide(Cloudflare.Flagship.ReadFlagsBinding)),
);

Declare the binding on env

Declaring the app on a Worker’s env maps it to the native Flagship runtime binding via InferEnv.

export const App = Cloudflare.Flagship.App("Flags", {});

export const Worker = Cloudflare.Worker("Worker", {
  main: "./src/worker.ts",
  env: { FLAGS: App },
});

export type WorkerEnv = Cloudflare.InferEnv<typeof Worker>;
//   { FLAGS: Flagship }

Async-style worker with the raw runtime binding

import type { WorkerEnv } from "../alchemy.run.ts";

export default {
  async fetch(request: Request, env: WorkerEnv) {
    const enabled = await env.FLAGS.getBooleanValue("new-checkout", false, {
      userId: "user-42",
    });
    return new Response(enabled ? "on" : "off");
  },
};

Flag

Source: src/Cloudflare/Flagship/Flag.ts

A feature flag in a Cloudflare Flagship app.

A flag maps a key to a set of variations plus targeting rules. Workers evaluate flags through the Flagship binding (or the REST evaluate endpoint); changing variations, rules, enablement, or the default variation takes effect without redeploying code. Everything except the flag key and the parent app is mutable in place.

Flag: Creating a Flag

Boolean flag

const app = yield* Cloudflare.Flagship.App("Flags", {});

const flag = yield* Cloudflare.Flagship.Flag("NewCheckout", {
  appId: app.appId,
  key: "new-checkout",
  defaultVariation: "off",
  variations: { off: false, on: true },
});

String flag with multiple variations

const flag = yield* Cloudflare.Flagship.Flag("CheckoutFlow", {
  appId: app.appId,
  key: "checkout-flow",
  defaultVariation: "v1",
  variations: { v1: "classic", v2: "express", v3: "one-click" },
});

Flag: Targeting Rules

Serve a variation to a specific country

const flag = yield* Cloudflare.Flagship.Flag("DarkMode", {
  appId: app.appId,
  key: "dark-mode",
  defaultVariation: "off",
  variations: { off: false, on: true },
  rules: [
    {
      priority: 1,
      conditions: [
        { attribute: "country", operator: "equals", value: "US" },
      ],
      serveVariation: "on",
    },
  ],
});

Percentage rollout

const flag = yield* Cloudflare.Flagship.Flag("NewSearch", {
  appId: app.appId,
  key: "new-search",
  defaultVariation: "off",
  variations: { off: false, on: true },
  rules: [
    {
      priority: 1,
      conditions: [],
      serveVariation: "on",
      rollout: { percentage: 25 },
    },
  ],
});

Flag: Toggling a Flag

const flag = yield* Cloudflare.Flagship.Flag("NewCheckout", {
  appId: app.appId,
  key: "new-checkout",
  enabled: false,
  defaultVariation: "off",
  variations: { off: false, on: true },
});

ReadFlags

Source: src/Cloudflare/Flagship/ReadFlags.ts

Bind a App to a Worker and obtain the Effect-native flag-evaluation client (get, getBooleanValue, getStringValue, …).

ReadFlags is a single identifier that is simultaneously the binding’s Context tag, its type, and the callable — yield* Cloudflare.Flagship.ReadFlags(app).

ReadFlags: Examples

const flags = yield* Cloudflare.Flagship.ReadFlags(MyApp);
const enabled = yield* flags.getBooleanValue("new-checkout", false);