FlagshipApp

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.

Creating an App

App with a generated name

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

App with an explicit name

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

Using the App

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

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

Binding to a Worker

Effect-style Worker (recommended)

FlagshipApp.bind(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.FlagshipApp("Flags", {});

Cloudflare.Worker(
  "FlagsWorker",
  { main: import.meta.filename },
  Effect.gen(function* () {
    const flags = yield* Cloudflare.FlagshipApp.bind(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.FlagshipBindingLive)),
);

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