Feature flags

Simple terms

Feature flags are controlled switches or payloads for engineering rollouts, not visual A/B test DOM changes.

Runtime toggles for off/on variants, typed payloads, rollout percentages, targeting, and source-experiment promotion.

Routes

• /flags

Implementation behavior

• Flags use the same targeting and rollout concepts as experiments but return a decision payload instead of DOM mutation behavior.
• A flag has status, key, rollout, targeting, variants, default/off value, and optional source experiment.
• Decision debugger explains why a visitor would receive a variant.
• Flags can be activated, paused, archived, or created from successful experiments.

How to use it

• Use flags when engineering needs a controlled rollout or remote configuration.
• Keep payloads typed and stable so application code can consume them safely.
• Test decisions with the debugger before activating.
• Archive flags that are permanently shipped in application code.

When not to use it

• Do not use a flag when you need experiment analytics and variant conversion tracking.
• Do not put secret or unsafe values in flag payloads consumed by the browser.
• Do not keep temporary rollout flags alive after the feature is permanently shipped.

Implementation source

• Pages live under src/app/(dashboard)/flags.
• Handlers live under /api/flags plus activate, pause, and archive routes.
• Flags share targeting and rollout ideas with experiments but return typed decision payloads instead of DOM mutations.

Data and API

• Flag and flag variant models plus targeting JSON.
• APIs under /api/flags, /api/flags/[id], /api/flags/[id]/activate, /api/flags/[id]/pause, /api/flags/[id]/archive, and experiment-to-flag creation.
• Runtime decisions are delivered through configuration and flag evaluation endpoints.

Failure modes

• Application sees default value: flag paused, key mismatch, targeting miss, or rollout percentage excludes visitor.
• Bad payload breaks consuming app code: validate schema and defaults before activation.
• Old flags create confusion: archive retired rollouts.

Ordered audiences through the API and CLI

A personalization can show different versions to different audiences. Audiences are evaluated in order. Each audience chooses an experience and a rollout; its holdback sees the flag's Off version. When “stop after match” is enabled, later audiences are skipped after a match, including a holdback assignment.

Use apex flags experiences create or update with a JSON file to save the experience's value, visual changes, CSS or JavaScript. Use apex flags rules set to replace the audience list and apex flags rules reorder to change its order. The API offers the same actions under a flag's rules and experiences paths. Writes check the parent flag version to prevent overwriting another editor's changes. If a save reports a conflict, reload the flag before saving again.

Removing an audience preserves its history. Experiences that an active or historical audience references cannot be deleted. The flag's Off and On versions stay in place, and goals remain attached to the whole personalization. A flag with no audiences keeps its existing rollout behavior.