Skip to content

Commit d8c2378

Browse files
roerohanroerohan
committed
Add Flagship feature flags documentation
1 parent 48ad4a0 commit d8c2378

18 files changed

Lines changed: 1246 additions & 0 deletions

‎src/content/docs/flagship/binding/index.mdx‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
pcx_content_type: overview
3+
title: Binding API
4+
sidebar:
5+
order: 5
6+
---
7+
8+
import { DirectoryListing } from "~/components";
9+
10+
Workers access Flagship through the `env.FLAGS` binding. The binding provides type-safe methods for evaluating feature flags. If an evaluation fails or a flag is not found, the method returns the default value you provide.
11+
12+
To add the binding, configure your Wrangler file and run `npx wrangler types` to generate TypeScript types. Refer to [Get started](/flagship/get-started/) for setup instructions.
13+
14+
```ts
15+
export default {
16+
async fetch(request: Request, env: Env): Promise<Response> {
17+
const enabled = await env.FLAGS.getBooleanValue("new-feature", false, {
18+
userId: "user-42",
19+
});
20+
return new Response(enabled ? "Feature on" : "Feature off");
21+
},
22+
};
23+
```
24+
25+
The binding has the type `Flagship` from the `@cloudflare/workers-types` package.
26+
27+
<DirectoryListing />

‎src/content/docs/flagship/binding/methods.mdx‎

Lines changed: 252 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,252 @@
1+
---
2+
pcx_content_type: reference
3+
title: Methods
4+
sidebar:
5+
order: 2
6+
---
7+
8+
The Flagship binding provides the following methods for evaluating feature flags. All methods are asynchronous and return a `Promise`. Evaluation methods never throw — they always return a value, falling back to the `defaultValue` you provide on errors.
9+
10+
Refer to the [types reference](/flagship/binding/types/) for the definitions of `FlagshipEvaluationContext` and `FlagshipEvaluationDetails`.
11+
12+
## `get()`
13+
14+
Returns the raw flag value without type checking. Use this method when the flag type is not known at compile time.
15+
16+
```ts
17+
get(flagKey: string, defaultValue?: unknown, context?: FlagshipEvaluationContext): Promise<unknown>
18+
```
19+
20+
| Parameter | Type | Required | Description |
21+
| -------------- | --------------------------- | -------- | ------------------------------------------------------------------------- |
22+
| `flagKey` | `string` | Yes | The key of the flag to evaluate. |
23+
| `defaultValue` | `unknown` | No | The fallback value returned if evaluation fails or the flag is not found. |
24+
| `context` | `FlagshipEvaluationContext` | No | Key-value attributes for targeting rules. |
25+
26+
```ts
27+
const value = await env.FLAGS.get("checkout-flow", "v1", {
28+
userId: "user-42",
29+
});
30+
```
31+
32+
## `getBooleanValue()`
33+
34+
Returns the flag value as a `boolean`.
35+
36+
```ts
37+
getBooleanValue(flagKey: string, defaultValue: boolean, context?: FlagshipEvaluationContext): Promise<boolean>
38+
```
39+
40+
| Parameter | Type | Required | Description |
41+
| -------------- | --------------------------- | -------- | ------------------------------------------------------------------------- |
42+
| `flagKey` | `string` | Yes | The key of the flag to evaluate. |
43+
| `defaultValue` | `boolean` | Yes | The fallback value returned if evaluation fails or the flag is not found. |
44+
| `context` | `FlagshipEvaluationContext` | No | Key-value attributes for targeting rules. |
45+
46+
```ts
47+
const enabled = await env.FLAGS.getBooleanValue("dark-mode", false, {
48+
userId: "user-42",
49+
});
50+
```
51+
52+
## `getStringValue()`
53+
54+
Returns the flag value as a `string`.
55+
56+
```ts
57+
getStringValue(flagKey: string, defaultValue: string, context?: FlagshipEvaluationContext): Promise<string>
58+
```
59+
60+
| Parameter | Type | Required | Description |
61+
| -------------- | --------------------------- | -------- | ------------------------------------------------------------------------- |
62+
| `flagKey` | `string` | Yes | The key of the flag to evaluate. |
63+
| `defaultValue` | `string` | Yes | The fallback value returned if evaluation fails or the flag is not found. |
64+
| `context` | `FlagshipEvaluationContext` | No | Key-value attributes for targeting rules. |
65+
66+
```ts
67+
const variant = await env.FLAGS.getStringValue("checkout-flow", "v1", {
68+
userId: "user-42",
69+
country: "US",
70+
});
71+
```
72+
73+
## `getNumberValue()`
74+
75+
Returns the flag value as a `number`.
76+
77+
```ts
78+
getNumberValue(flagKey: string, defaultValue: number, context?: FlagshipEvaluationContext): Promise<number>
79+
```
80+
81+
| Parameter | Type | Required | Description |
82+
| -------------- | --------------------------- | -------- | ------------------------------------------------------------------------- |
83+
| `flagKey` | `string` | Yes | The key of the flag to evaluate. |
84+
| `defaultValue` | `number` | Yes | The fallback value returned if evaluation fails or the flag is not found. |
85+
| `context` | `FlagshipEvaluationContext` | No | Key-value attributes for targeting rules. |
86+
87+
```ts
88+
const maxRetries = await env.FLAGS.getNumberValue("max-retries", 3, {
89+
plan: "enterprise",
90+
});
91+
```
92+
93+
## `getObjectValue()`
94+
95+
Returns the flag value as a typed object. Use the generic parameter `T` to specify the expected shape.
96+
97+
```ts
98+
getObjectValue<T extends object>(flagKey: string, defaultValue: T, context?: FlagshipEvaluationContext): Promise<T>
99+
```
100+
101+
| Parameter | Type | Required | Description |
102+
| -------------- | --------------------------- | -------- | ------------------------------------------------------------------------- |
103+
| `flagKey` | `string` | Yes | The key of the flag to evaluate. |
104+
| `defaultValue` | `T` | Yes | The fallback value returned if evaluation fails or the flag is not found. |
105+
| `context` | `FlagshipEvaluationContext` | No | Key-value attributes for targeting rules. |
106+
107+
```ts
108+
interface ThemeConfig {
109+
primaryColor: string;
110+
fontSize: number;
111+
}
112+
113+
const theme = await env.FLAGS.getObjectValue<ThemeConfig>(
114+
"theme-config",
115+
{ primaryColor: "#000", fontSize: 14 },
116+
{ userId: "user-42" },
117+
);
118+
```
119+
120+
## `getBooleanDetails()`
121+
122+
Returns the flag value as a `boolean` with evaluation metadata.
123+
124+
```ts
125+
getBooleanDetails(flagKey: string, defaultValue: boolean, context?: FlagshipEvaluationContext): Promise<FlagshipEvaluationDetails<boolean>>
126+
```
127+
128+
| Parameter | Type | Required | Description |
129+
| -------------- | --------------------------- | -------- | ------------------------------------------------------------------------- |
130+
| `flagKey` | `string` | Yes | The key of the flag to evaluate. |
131+
| `defaultValue` | `boolean` | Yes | The fallback value returned if evaluation fails or the flag is not found. |
132+
| `context` | `FlagshipEvaluationContext` | No | Key-value attributes for targeting rules. |
133+
134+
```ts
135+
const details = await env.FLAGS.getBooleanDetails("dark-mode", false, {
136+
userId: "user-42",
137+
});
138+
console.log(details.value); // true
139+
console.log(details.reason); // "TARGETING_MATCH"
140+
```
141+
142+
## `getStringDetails()`
143+
144+
Returns the flag value as a `string` with evaluation metadata.
145+
146+
```ts
147+
getStringDetails(flagKey: string, defaultValue: string, context?: FlagshipEvaluationContext): Promise<FlagshipEvaluationDetails<string>>
148+
```
149+
150+
| Parameter | Type | Required | Description |
151+
| -------------- | --------------------------- | -------- | ------------------------------------------------------------------------- |
152+
| `flagKey` | `string` | Yes | The key of the flag to evaluate. |
153+
| `defaultValue` | `string` | Yes | The fallback value returned if evaluation fails or the flag is not found. |
154+
| `context` | `FlagshipEvaluationContext` | No | Key-value attributes for targeting rules. |
155+
156+
```ts
157+
const details = await env.FLAGS.getStringDetails("checkout-flow", "v1", {
158+
userId: "user-42",
159+
});
160+
console.log(details.value); // "v2"
161+
console.log(details.variant); // "new"
162+
console.log(details.reason); // "TARGETING_MATCH"
163+
```
164+
165+
## `getNumberDetails()`
166+
167+
Returns the flag value as a `number` with evaluation metadata.
168+
169+
```ts
170+
getNumberDetails(flagKey: string, defaultValue: number, context?: FlagshipEvaluationContext): Promise<FlagshipEvaluationDetails<number>>
171+
```
172+
173+
| Parameter | Type | Required | Description |
174+
| -------------- | --------------------------- | -------- | ------------------------------------------------------------------------- |
175+
| `flagKey` | `string` | Yes | The key of the flag to evaluate. |
176+
| `defaultValue` | `number` | Yes | The fallback value returned if evaluation fails or the flag is not found. |
177+
| `context` | `FlagshipEvaluationContext` | No | Key-value attributes for targeting rules. |
178+
179+
```ts
180+
const details = await env.FLAGS.getNumberDetails("max-retries", 3, {
181+
plan: "enterprise",
182+
});
183+
console.log(details.value); // 5
184+
console.log(details.reason); // "TARGETING_MATCH"
185+
```
186+
187+
## `getObjectDetails()`
188+
189+
Returns the flag value as a typed object with evaluation metadata. Use the generic parameter `T` to specify the expected shape.
190+
191+
```ts
192+
getObjectDetails<T extends object>(flagKey: string, defaultValue: T, context?: FlagshipEvaluationContext): Promise<FlagshipEvaluationDetails<T>>
193+
```
194+
195+
| Parameter | Type | Required | Description |
196+
| -------------- | --------------------------- | -------- | ------------------------------------------------------------------------- |
197+
| `flagKey` | `string` | Yes | The key of the flag to evaluate. |
198+
| `defaultValue` | `T` | Yes | The fallback value returned if evaluation fails or the flag is not found. |
199+
| `context` | `FlagshipEvaluationContext` | No | Key-value attributes for targeting rules. |
200+
201+
```ts
202+
interface ThemeConfig {
203+
primaryColor: string;
204+
fontSize: number;
205+
}
206+
207+
const details = await env.FLAGS.getObjectDetails<ThemeConfig>(
208+
"theme-config",
209+
{ primaryColor: "#000", fontSize: 14 },
210+
{ userId: "user-42" },
211+
);
212+
console.log(details.value); // { primaryColor: "#0051FF", fontSize: 16 }
213+
console.log(details.variant); // "brand-refresh"
214+
```
215+
216+
## Error handling
217+
218+
Evaluation methods never throw. They always return a value. When an error occurs, the method returns the `defaultValue` you provided. Use the `*Details` variants to inspect what went wrong.
219+
220+
### Type mismatch
221+
222+
If you call a typed method on a flag with a different type (for example, `getBooleanValue` on a string flag), the method returns the default value. The `*Details` variants set `errorCode` to `"TYPE_MISMATCH"`.
223+
224+
```ts
225+
// Flag "checkout-flow" is a string flag, but you call getBooleanDetails.
226+
const details = await env.FLAGS.getBooleanDetails("checkout-flow", false);
227+
console.log(details.value); // false (the default value)
228+
console.log(details.errorCode); // "TYPE_MISMATCH"
229+
```
230+
231+
### Evaluation failure
232+
233+
If evaluation fails for any other reason (for example, a network error or missing flag), the method returns the default value. The `*Details` variants set `errorCode` to `"GENERAL"`.
234+
235+
```ts
236+
const details = await env.FLAGS.getStringDetails(
237+
"nonexistent-flag",
238+
"fallback",
239+
);
240+
console.log(details.value); // "fallback"
241+
console.log(details.errorCode); // "GENERAL"
242+
```
243+
244+
## Parameters reference
245+
246+
The following table summarizes the parameters shared across all evaluation methods.
247+
248+
| Parameter | Type | Required | Description |
249+
| -------------- | --------------------------- | ------------------ | ----------------------------------------------------------------------------------------------- |
250+
| `flagKey` | `string` | Yes | The key of the flag to evaluate. |
251+
| `defaultValue` | varies | Yes (except `get`) | The fallback value returned if evaluation fails or the flag is not found. |
252+
| `context` | `FlagshipEvaluationContext` | No | Key-value attributes for targeting rules (for example, `{ userId: "user-42", country: "US" }`). |

‎src/content/docs/flagship/binding/types.mdx‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
pcx_content_type: reference
3+
title: Types
4+
sidebar:
5+
order: 1
6+
---
7+
8+
The Flagship binding uses the following TypeScript types. These are available from the `@cloudflare/workers-types` package after running `npx wrangler types`.
9+
10+
## `Flagship`
11+
12+
The binding type. Each Flagship binding in your Wrangler configuration is typed as `Flagship` on the `Env` interface.
13+
14+
```ts
15+
interface Env {
16+
FLAGS: Flagship;
17+
}
18+
```
19+
20+
Refer to the [methods reference](/flagship/binding/) for the full list of evaluation methods available on the binding.
21+
22+
## `FlagshipEvaluationContext`
23+
24+
A record of attribute names to values passed for [targeting rules](/flagship/targeting/). Use this to provide user attributes such as user ID, country, or plan type.
25+
26+
```ts
27+
type FlagshipEvaluationContext = Record<string, string | number | boolean>;
28+
```
29+
30+
## `FlagshipEvaluationDetails`
31+
32+
Returned by the `*Details` methods. Contains the evaluated value and metadata about how Flagship resolved the flag.
33+
34+
```ts
35+
interface FlagshipEvaluationDetails<T> {
36+
flagKey: string;
37+
value: T;
38+
variant?: string;
39+
reason?: string;
40+
errorCode?: string;
41+
errorMessage?: string;
42+
}
43+
```
44+
45+
| Property | Type | Description |
46+
| -------------- | -------- | -------------------------------------------------------------------------------------- |
47+
| `flagKey` | `string` | The key of the evaluated flag. |
48+
| `value` | `T` | The resolved flag value. |
49+
| `variant` | `string` | The name of the matched variation, if any. |
50+
| `reason` | `string` | Why the flag resolved to this value (for example, `"TARGETING_MATCH"` or `"DEFAULT"`). |
51+
| `errorCode` | `string` | An error code if evaluation failed (for example, `"TYPE_MISMATCH"` or `"GENERAL"`). |
52+
| `errorMessage` | `string` | A human-readable description of the error. |
53+
54+
Refer to [evaluation reasons and error codes](/flagship/reference/evaluation-reasons/) for the full list of possible values.

0 commit comments

Comments
 (0)