1# Flagship Configuration
2 
3## Wrangler Binding Setup
4 
5Add a Flagship binding to your Wrangler config to access flags via `env.FLAGS`.
6 
7### Single App
8 
9```jsonc
10// wrangler.jsonc
11{
12  "flagship": {
13    "binding": "FLAGS",
14    "app_id": "<APP_ID>"
15  }
16}
17```
18 
19```toml
20# wrangler.toml
21[flagship]
22binding = "FLAGS"
23app_id = "<APP_ID>"
24```
25 
26### Multiple Apps
27 
28```jsonc
29// wrangler.jsonc
30{
31  "flagship": [
32    {
33      "binding": "FLAGS",
34      "app_id": "<APP_ID_1>"
35    },
36    {
37      "binding": "EXPERIMENT_FLAGS",
38      "app_id": "<APP_ID_2>"
39    }
40  ]
41}
42```
43 
44```toml
45# wrangler.toml
46[[flagship]]
47binding = "FLAGS"
48app_id = "<APP_ID_1>"
49 
50[[flagship]]
51binding = "EXPERIMENT_FLAGS"
52app_id = "<APP_ID_2>"
53```
54 
55### Generate Types
56 
57After adding the binding, generate TypeScript types:
58 
59```bash
60npx wrangler types
61```
62 
63This creates the `Env` interface with each binding typed as `Flagship`:
64 
65```typescript
66interface Env {
67  FLAGS: Flagship;
68  EXPERIMENT_FLAGS: Flagship; // if multiple
69}
70```
71 
72The `Flagship` type comes from `@cloudflare/workers-types`.
73 
74---
75 
76## OpenFeature SDK Installation
77 
78### Server-Side (Workers, Node.js)
79 
80```bash
81npm i @cloudflare/flagship @openfeature/server-sdk
82```
83 
84### Browser
85 
86```bash
87npm i @cloudflare/flagship @openfeature/web-sdk
88```
89 
90---
91 
92## SDK Provider Setup
93 
94### Server Provider — With Binding (Workers)
95 
96Recommended approach inside Workers. No HTTP overhead, auth handled automatically.
97 
98```typescript
99import { OpenFeature } from "@openfeature/server-sdk";
100import { FlagshipServerProvider } from "@cloudflare/flagship";
101 
102export default {
103  async fetch(request: Request, env: Env): Promise<Response> {
104    await OpenFeature.setProviderAndWait(
105      new FlagshipServerProvider({ binding: env.FLAGS }),
106    );
107    const client = OpenFeature.getClient();
108    // ... evaluate flags
109  },
110};
111```
112 
113### Server Provider — With App ID (Node.js)
114 
115For non-Worker runtimes. Requires an API token with Flagship read permissions.
116 
117```typescript
118import { OpenFeature } from "@openfeature/server-sdk";
119import { FlagshipServerProvider } from "@cloudflare/flagship";
120 
121await OpenFeature.setProviderAndWait(
122  new FlagshipServerProvider({
123    appId: "<APP_ID>",
124    accountId: "<ACCOUNT_ID>",
125    authToken: "<API_TOKEN>",
126  }),
127);
128const client = OpenFeature.getClient();
129```
130 
131### Client Provider (Browser)
132 
133Pre-fetches flags on init, then evaluates synchronously. Only `prefetchFlags` are available.
134 
135```typescript
136import { OpenFeature } from "@openfeature/web-sdk";
137import { FlagshipClientProvider } from "@cloudflare/flagship";
138 
139await OpenFeature.setProviderAndWait(
140  new FlagshipClientProvider({
141    appId: "<APP_ID>",
142    accountId: "<ACCOUNT_ID>",
143    authToken: "<API_TOKEN>",
144    prefetchFlags: ["promo-banner", "dark-mode", "max-uploads"],
145  }),
146);
147await OpenFeature.setContext({ targetingKey: "user-42", plan: "enterprise" });
148const client = OpenFeature.getClient();
149```
150 
151### Provider Options Reference
152 
153**FlagshipServerProvider:**
154 
155| Option | Type | Required | Description |
156|--------|------|----------|-------------|
157| `binding` | `Flagship` | No | Binding from `env.FLAGS`. Use inside Workers. |
158| `appId` | string | No | App ID from dashboard. Required without binding. |
159| `accountId` | string | No | Cloudflare account ID. Required without binding. |
160| `authToken` | string | No | API token with Flagship read permissions. Required without binding. |
161 
162Provide either `binding` or all three of `appId` + `accountId` + `authToken`.
163 
164**FlagshipClientProvider:**
165 
166| Option | Type | Required | Description |
167|--------|------|----------|-------------|
168| `appId` | string | Yes | App ID from dashboard |
169| `accountId` | string | Yes | Cloudflare account ID |
170| `authToken` | string | Yes | API token with Flagship read permissions |
171| `prefetchFlags` | string[] | Yes | Flag keys to prefetch. Unlisted flags return `FLAG_NOT_FOUND`. |
172 
173---
174 
175## REST API Authentication
176 
177For managing flags via the REST API (create, update, delete), set these environment variables:
178 
179| Variable | Description |
180|----------|-------------|
181| `CLOUDFLARE_ACCOUNT_ID` | Your Cloudflare account ID |
182| `CLOUDFLARE_API_TOKEN` | API token with Flagship permissions |
183| `FLAGSHIP_APP_ID` | Target app UUID (from dashboard under **Compute > Flagship**, or `GET /apps`) |
184 
185Base URL: `https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/flagship`
186 
187```bash
188curl -s -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
189  "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/flagship/apps" | jq .
190```
191 
192App IDs are shown in the Cloudflare dashboard under **Compute > Flagship**.
193 
194---
195 
196## Local Development
197 
198Flagship bindings work in local dev with `wrangler dev`. Flag evaluation uses the live Flagship configuration — there is no local flag store. Ensure the `app_id` in your Wrangler config points to a valid app.
199 
200```bash
201npx wrangler dev
202```
203