1# Cloudflare Flagship
2 
3Feature flag service for controlling feature visibility without redeploying code. Define flags with targeting rules and percentage-based rollouts, then evaluate them in Workers via a native binding or from any JavaScript runtime via the OpenFeature SDK.
4 
5## When to Use
6 
7| Need | Use Flagship? | Alternative |
8|------|--------------|-------------|
9| Feature toggles (on/off) | Yes | — |
10| Gradual rollouts (percentage-based) | Yes | — |
11| A/B testing with attribute targeting | Yes | — |
12| Multi-variant configuration delivery | Yes | — |
13| Environment-specific config (dev/staging/prod) | Consider | Wrangler environments, secrets |
14| Static config that never changes | No | `wrangler.jsonc` vars |
15| Per-request rate limiting | No | Rate Limiting rules |
16 
17## Key Concepts
18 
19- **Apps** — Top-level organizational unit. Maps to a project or service. Each account can have multiple apps.
20- **Flags** — Named feature toggles with a key, variations, targeting rules, and enabled/disabled state.
21- **Variations** — Possible values a flag returns. Types: boolean, string, number, JSON object. All variations on a flag must share the same type.
22- **Targeting rules** — Sequential, priority-ordered conditions that determine which variation to serve. First match wins; no match returns the default.
23- **Evaluation context** — Key-value attributes (`userId`, `country`, `plan`, etc.) passed at evaluation time for rule matching and rollout bucketing.
24- **Percentage rollouts** — Gradually release to a fraction of users. Consistent hashing on a configurable attribute ensures sticky bucketing.
25 
26## Two Evaluation Paths
27 
28| Path | Runtime | Package | Latency | Auth |
29|------|---------|---------|---------|------|
30| **Binding** (`env.FLAGS`) | Workers only | `@cloudflare/workers-types` | Lowest (no HTTP) | Automatic via binding |
31| **OpenFeature SDK** | Workers, Node.js, browser | `@cloudflare/flagship` + `@openfeature/server-sdk` or `@openfeature/web-sdk` | HTTP per eval (server) or prefetch (client) | API token or binding passthrough |
32 
33**Recommendation:** Use the binding inside Workers. Use the SDK when running outside Workers or when you need OpenFeature vendor-neutrality.
34 
35## Reading Order
36 
37| Task | Read |
38|------|------|
39| Set up Flagship in a Worker | `configuration.md` → `api.md` |
40| Evaluate flags in code | `configuration.md` → `patterns.md` |
41| Manage flags via REST API | `api.md` → `patterns.md` |
42| Design targeting rules & rollouts | `patterns.md` → `gotchas.md` |
43| Debug flag evaluation issues | `gotchas.md` → `api.md` |
44 
45## In This Reference
46 
47- **[api.md](./api.md)** — REST API endpoints, binding methods, OpenFeature SDK, schemas
48- **[configuration.md](./configuration.md)** — Wrangler binding setup, SDK installation, TypeScript types
49- **[patterns.md](./patterns.md)** — Flag CRUD via API, targeting rules, rollouts, OpenFeature usage
50- **[gotchas.md](./gotchas.md)** — Common errors, limits, anti-patterns, troubleshooting
51 
52## See Also
53 
54- **[../workers/](../workers/)** — Workers runtime (Flagship runs inside Workers)
55- **[../kv/](../kv/)** — KV storage (Flagship uses KV infrastructure for flag delivery)
56- **[../wrangler/](../wrangler/)** — Wrangler CLI for deployment and config
57