Source from repo
Cloudflare Platform Skill

Comprehensive Cloudflare platform skill covering Workers, D1, R2, KV, AI, Durable Objects, and security.
cloudflareGitHub cloudflareSource repo Original GitHub link Publisher page
Files
321
Skill
n/a
Size
1.4 MB
Entrypoint
SKILL.md
Format
git-repo
Open file
references/flagship/patterns.md

Syntax-highlighted preview of this file as included in the skill package.
Rendered Source
markdown425 linesFree
references/flagship/patterns.md
1# Flagship Patterns & Best Practices
2 
3## Evaluating Flags in Workers (Binding)
4 
5### Simple Boolean Toggle
6 
7```typescript
8export default {
9  async fetch(request: Request, env: Env): Promise<Response> {
10    const showNewUI = await env.FLAGS.getBooleanValue("new-ui", false, {
11      userId: "user-42",
12    });
13 
14    if (showNewUI) {
15      return new Response("New UI");
16    }
17    return new Response("Classic UI");
18  },
19};
20```
21 
22### Multi-Variant String Flag
23 
24```typescript
25const checkoutFlow = await env.FLAGS.getStringValue(
26  "checkout-flow",
27  "original",
28  { userId, country: "US" },
29);
30 
31switch (checkoutFlow) {
32  case "streamlined":
33    return handleStreamlined(request);
34  case "one-click":
35    return handleOneClick(request);
36  default:
37    return handleOriginal(request);
38}
39```
40 
41### JSON Config Flag
42 
43```typescript
44interface RateLimitConfig {
45  rpm: number;
46  burst: number;
47}
48 
49const limits = await env.FLAGS.getObjectValue<RateLimitConfig>(
50  "rate-limits",
51  { rpm: 100, burst: 20 },
52  { plan: userPlan },
53);
54```
55 
56### Using Details for Observability
57 
58```typescript
59const details = await env.FLAGS.getBooleanDetails("new-checkout", false, {
60  userId: "user-42",
61});
62 
63console.log(details.value);     // true
64console.log(details.variant);   // "on"
65console.log(details.reason);    // "TARGETING_MATCH"
66console.log(details.errorCode); // undefined (no error)
67```
68 
69---
70 
71## Evaluating Flags with OpenFeature (Workers)
72 
73### Binding Passthrough (Recommended)
74 
75```typescript
76import { OpenFeature } from "@openfeature/server-sdk";
77import { FlagshipServerProvider } from "@cloudflare/flagship";
78 
79export default {
80  async fetch(request: Request, env: Env): Promise<Response> {
81    await OpenFeature.setProviderAndWait(
82      new FlagshipServerProvider({ binding: env.FLAGS }),
83    );
84    const client = OpenFeature.getClient();
85 
86    const enabled = await client.getBooleanValue("new-checkout", false, {
87      targetingKey: "user-42",
88      plan: "enterprise",
89      country: "US",
90    });
91 
92    return new Response(enabled ? "New checkout" : "Standard checkout");
93  },
94};
95```
96 
97### Migration from Another Provider
98 
99Only the provider initialization changes — evaluation call sites stay the same:
100 
101```typescript
102// ❌ Before (LaunchDarkly)
103await OpenFeature.setProviderAndWait(
104  new LaunchDarklyProvider({ sdkKey: "..." }),
105);
106 
107// ✅ After (Flagship)
108await OpenFeature.setProviderAndWait(
109  new FlagshipServerProvider({ binding: env.FLAGS }),
110);
111 
112// Evaluation code is unchanged
113const enabled = await client.getBooleanValue("my-flag", false, {
114  targetingKey: "user-42",
115});
116```
117 
118---
119 
120## Managing Flags via REST API
121 
122All examples use `api.cloudflare.com`. Set `CLOUDFLARE_ACCOUNT_ID`, `FLAGSHIP_APP_ID`, and `CLOUDFLARE_API_TOKEN` first.
123 
124### Create a Boolean Flag
125 
126```bash
127curl -s -X POST \
128  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
129  -H "Content-Type: application/json" \
130  -d '{
131    "key": "new-feature",
132    "default_variation": "off",
133    "variations": { "on": true, "off": false },
134    "rules": [],
135    "description": "Enable the new feature",
136    "enabled": false
137  }' \
138  "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/flagship/apps/$FLAGSHIP_APP_ID/flags" | jq .
139```
140 
141### Create a Flag with Internal-Only Targeting
142 
143```bash
144curl -s -X POST \
145  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
146  -H "Content-Type: application/json" \
147  -d '{
148    "key": "beta-feature",
149    "default_variation": "off",
150    "variations": { "on": true, "off": false },
151    "rules": [
152      {
153        "priority": 1,
154        "conditions": [
155          { "attribute": "email", "operator": "ends_with", "value": "@cloudflare.com" }
156        ],
157        "serve_variation": "on"
158      }
159    ],
160    "description": "Beta feature for internal users",
161    "enabled": true
162  }' \
163  "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/flagship/apps/$FLAGSHIP_APP_ID/flags" | jq .
164```
165 
166### Create a JSON Config Flag
167 
168```bash
169curl -s -X POST \
170  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
171  -H "Content-Type: application/json" \
172  -d '{
173    "key": "rate-limits",
174    "default_variation": "standard",
175    "variations": {
176      "standard": { "rpm": 100, "burst": 20 },
177      "premium": { "rpm": 1000, "burst": 200 }
178    },
179    "rules": [
180      {
181        "priority": 1,
182        "conditions": [
183          { "attribute": "plan", "operator": "in", "value": ["enterprise", "business"] }
184        ],
185        "serve_variation": "premium"
186      }
187    ],
188    "description": "Rate limit configuration by plan",
189    "enabled": true
190  }' \
191  "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/flagship/apps/$FLAGSHIP_APP_ID/flags" | jq .
192```
193 
194### Read a Flag
195 
196```bash
197curl -s -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
198  "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/flagship/apps/$FLAGSHIP_APP_ID/flags/new-feature" | jq .
199```
200 
201### List All Flags (with pagination)
202 
203```bash
204curl -s -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
205  "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/flagship/apps/$FLAGSHIP_APP_ID/flags?limit=50" | jq .
206```
207 
208If `nextCursor` is non-null, fetch the next page:
209 
210```bash
211curl -s -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
212  "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/flagship/apps/$FLAGSHIP_APP_ID/flags?limit=50&cursor=<nextCursor>" | jq .
213```
214 
215### Update a Flag (Full Replace)
216 
217Updates use PUT with the full `FlagDefinition`. Always GET first, modify, then PUT back.
218 
219```bash
220# 1. Read current flag
221FLAG=$(curl -s -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
222  "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/flagship/apps/$FLAGSHIP_APP_ID/flags/new-feature" | jq '.data')
223 
224# 2. Modify (e.g., enable the flag)
225UPDATED=$(echo "$FLAG" | jq '.enabled = true')
226 
227# 3. PUT back
228echo "$UPDATED" | curl -s -X PUT \
229  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
230  -H "Content-Type: application/json" \
231  -d @- \
232  "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/flagship/apps/$FLAGSHIP_APP_ID/flags/new-feature" | jq .
233```
234 
235### Toggle a Flag On
236 
237Read-modify-write to set `enabled: true`:
238 
239```bash
240BASE="https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/flagship/apps/$FLAGSHIP_APP_ID/flags"
241 
242FLAG=$(curl -s -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" "$BASE/new-feature" | jq '.data')
243UPDATED=$(echo "$FLAG" | jq '.enabled = true')
244echo "$UPDATED" | curl -s -X PUT \
245  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
246  -H "Content-Type: application/json" \
247  -d @- "$BASE/new-feature" | jq .
248```
249 
250### Toggle a Flag Off (Disable)
251 
252Same pattern, set `enabled: false`. The flag immediately returns its default variation for all evaluations.
253 
254```bash
255BASE="https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/flagship/apps/$FLAGSHIP_APP_ID/flags"
256 
257FLAG=$(curl -s -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" "$BASE/new-feature" | jq '.data')
258UPDATED=$(echo "$FLAG" | jq '.enabled = false')
259echo "$UPDATED" | curl -s -X PUT \
260  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
261  -H "Content-Type: application/json" \
262  -d @- "$BASE/new-feature" | jq .
263```
264 
265### Add a Targeting Rule to an Existing Flag
266 
267Append a rule to the existing rules array. Pick a priority that doesn't collide with existing rules.
268 
269```bash
270BASE="https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/flagship/apps/$FLAGSHIP_APP_ID/flags"
271 
272FLAG=$(curl -s -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" "$BASE/new-feature" | jq '.data')
273UPDATED=$(echo "$FLAG" | jq '.rules += [{
274  "priority": 2,
275  "conditions": [{ "attribute": "plan", "operator": "equals", "value": "enterprise" }],
276  "serve_variation": "on"
277}]')
278echo "$UPDATED" | curl -s -X PUT \
279  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
280  -H "Content-Type: application/json" \
281  -d @- "$BASE/new-feature" | jq .
282```
283 
284### Change Rollout Percentage
285 
286Update the rollout percentage on an existing rule (e.g., rule at index 0):
287 
288```bash
289BASE="https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/flagship/apps/$FLAGSHIP_APP_ID/flags"
290 
291FLAG=$(curl -s -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" "$BASE/gradual-rollout" | jq '.data')
292UPDATED=$(echo "$FLAG" | jq '.rules[0].rollout.percentage = 50')
293echo "$UPDATED" | curl -s -X PUT \
294  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
295  -H "Content-Type: application/json" \
296  -d @- "$BASE/gradual-rollout" | jq .
297```
298 
299### Change Default Variation
300 
301```bash
302BASE="https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/flagship/apps/$FLAGSHIP_APP_ID/flags"
303 
304FLAG=$(curl -s -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" "$BASE/new-feature" | jq '.data')
305UPDATED=$(echo "$FLAG" | jq '.default_variation = "on"')
306echo "$UPDATED" | curl -s -X PUT \
307  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
308  -H "Content-Type: application/json" \
309  -d @- "$BASE/new-feature" | jq .
310```
311 
312### Add a New Variation
313 
314```bash
315BASE="https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/flagship/apps/$FLAGSHIP_APP_ID/flags"
316 
317FLAG=$(curl -s -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" "$BASE/checkout-flow" | jq '.data')
318UPDATED=$(echo "$FLAG" | jq '.variations["treatment-c"] = "minimal"')
319echo "$UPDATED" | curl -s -X PUT \
320  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
321  -H "Content-Type: application/json" \
322  -d @- "$BASE/checkout-flow" | jq .
323```
324 
325### Remove a Rule
326 
327Remove a rule by filtering on priority:
328 
329```bash
330BASE="https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/flagship/apps/$FLAGSHIP_APP_ID/flags"
331 
332FLAG=$(curl -s -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" "$BASE/new-feature" | jq '.data')
333UPDATED=$(echo "$FLAG" | jq '.rules = [.rules[] | select(.priority != 2)]')
334echo "$UPDATED" | curl -s -X PUT \
335  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
336  -H "Content-Type: application/json" \
337  -d @- "$BASE/new-feature" | jq .
338```
339 
340### Delete a Flag
341 
342```bash
343curl -s -X DELETE \
344  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
345  "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/flagship/apps/$FLAGSHIP_APP_ID/flags/old-feature" | jq .
346```
347 
348---
349 
350## Targeting Rule Patterns
351 
352### Enterprise-Only Access
353 
354```json
355{
356  "priority": 1,
357  "conditions": [
358    { "attribute": "plan", "operator": "equals", "value": "enterprise" }
359  ],
360  "serve_variation": "on"
361}
362```
363 
364### Country-Based Targeting with Logical AND/OR
365 
366Target enterprise users in the US or Canada:
367 
368```json
369{
370  "priority": 1,
371  "conditions": [
372    {
373      "logical_operator": "AND",
374      "clauses": [
375        { "attribute": "plan", "operator": "equals", "value": "enterprise" },
376        {
377          "logical_operator": "OR",
378          "clauses": [
379            { "attribute": "country", "operator": "equals", "value": "US" },
380            { "attribute": "country", "operator": "equals", "value": "CA" }
381          ]
382        }
383      ]
384    }
385  ],
386  "serve_variation": "on"
387}
388```
389 
390### Percentage Rollout
391 
392Gradually roll out to 10% of users:
393 
394```json
395{
396  "priority": 1,
397  "conditions": [
398    { "attribute": "targetingKey", "operator": "not_equals", "value": "" }
399  ],
400  "serve_variation": "on",
401  "rollout": {
402    "percentage": 10,
403    "attribute": "targetingKey"
404  }
405}
406```
407 
408### Progressive Rollout Workflow
409 
4101. Create flag with 5% rollout, enable it
4112. Monitor metrics
4123. Increase to 25% → 50% → 100% by updating the `rollout.percentage`
4134. Once at 100%, remove the rule and set `default_variation` to the winning variation
4145. Eventually remove the flag and the code branch
415 
416---
417 
418## Safe Deletion Workflow
419 
4201. **Disable** the flag first (`enabled: false`) — confirms nothing depends on it being active
4212. **Monitor** for unexpected behavior
4223. **Remove** flag evaluation code from your application
4234. **Deploy** the code change
4245. **Delete** the flag via API
425
Preparing the source view

Cloudflare Platform Skill

references/flagship/patterns.md
