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

Type	Example Values	Use Case
Boolean	`true`, `false`	Feature on/off
String	`"variant-a"`, `"blue"`	A/B test variants, themes
Number	`100`, `3.14`	Limits, timeouts, percentages
Object	`{"theme": "dark", "maxItems": 10}`	Complex configuration

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 ───────^

Choose defaults that are safe. If your flag controls a new feature, default to the old behavior.

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

Navigate to your project in the dashboard
Click Flags > Create Flag
Enter the key and select a type
Define your variants
Set the default variant

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