Feature Flags

A feature flag controls runtime behavior. Each flag has a key, type, variants, and a default value.

Flag Key

A unique identifier using kebab-case:

dark-mode
new-checkout-flow
max-upload-size
feature-config-v2

Keys must match the pattern ^[a-z0-9]+(?:-[a-z0-9]+)*$.

Flag Types

Variants

Named values the flag can return. Every flag has at least two variants:

// Boolean flag
variants: {
  "on": true,
  "off": false
}
 
// String flag for A/B testing
variants: {
  "control": "old-checkout",
  "treatment-a": "new-checkout-v1",
  "treatment-b": "new-checkout-v2"
}
 
// Number flag for limits
variants: {
  "default": 100,
  "premium": 1000,
  "enterprise": 10000
}

Default Value

The value returned when:

• The flag is disabled
• No targeting rules match
• An error occurs during evaluation

// If something goes wrong, this value is used
const maxItems = await client.getNumberValue('max-items', 50);
//                                           default ───────^

Enabled vs Disabled

Each flag has an enabled/disabled state per environment:

• Disabled: Always returns the default variant
• Enabled: Evaluates targeting rules, returns matching variant

This gives you a kill switch. Something wrong with the new checkout? Disable the flag. All users get the old checkout instantly.

Creating a Flag

1. Navigate to your project in the dashboard
2. Click Flags > Create Flag
3. Enter the key and select a type
4. Define your variants
5. Set the default variant

The flag is created disabled. Configure targeting rules, then enable it when ready.