LiftCanary

Guides

Feature flags and rollouts

Release behind flags, roll out gradually, switch off instantly and use remote config.

Create a flag#

Flags → New flag asks for a key (1–64 characters: a-z, 0-9, _, -), a name and a description. Keys can't change later, because your code refers to them. A new flag is a simple on/off flag, switched off in every environment, so creating it changes nothing for users.

The key is filled in from the name as you type and checked on the spot: allowed characters, length, and whether another flag in the project already uses it. A preview shows the variations that will be created and the line of code that reads the flag. ⌘/Ctrl + Enter creates it.

The type on the left sets up common shapes:

  • On / off: off / on, for releases, gradual rollouts and kill switches.
  • A/B test: control and treatment variations, ready for an experiment.
  • AI config: model, prompt and params variables with Off, Current and Challenger variations. See AI configs.

Variations and variables#

Variations → Edit adds, removes and reorders variations, names them, sets each one's on/off state, and manages variables and their per-variation values. Variables are typed (text, number, true/false, JSON) and validated: a number variable can't be given a string.

  • Removing a variation that targeting still uses is refused, with the environment and rule named.
  • Renaming a variation key rewrites every environment (off and default variation, overrides, rule allocations) in one step. It's refused while the variation is in a running experiment, because its exposures are recorded under the old key. Code that compares variationKey must change too, which is why reading variables is preferred.

Targeting per environment#

Open a flag and pick an environment. The editor shows, in evaluation order:

SettingWhat it does
On / offThe kill switch. Off serves the off variation to everyone, immediately.
User overridesUser id → variation. Checked before rules; ideal for QA, demos and allowlists.
RulesTop to bottom. The first rule whose conditions match and whose traffic includes the user decides. Drag to reorder.
Default variationServed when the flag is on but no rule took the user. Defaults to the off variation.

Rules#

A rule has conditions (empty = everyone; built with the same editor as audiences), a traffic percentage and a split across variations. The editor checks that the split adds up to 100% as you type. Conditions that the visual editor can't show open as JSON, so nothing is ever lost.

Each rule has a server-generated salt that never changes, so editing or renaming a rule never reshuffles users. Raising traffic only adds users; those already in keep their variation.

Gradual rollouts#

To release safely, add a rollout rule that gives on to a growing share of users:

  1. Start at 5% for internal users (an audience such as email ends with @yourcompany.com), then 5% of everyone.
  2. Raise it to 25%, 50% and 100% as error rates and support tickets stay flat.
  3. If something goes wrong, switch the flag off: everyone gets the off variation within the SDK's refresh time, with no deploy.

Kill switches#

The flag list has an on/off switch per environment. Production-like environments ask for confirmation first. From the API:

Terminal
curl -X POST https://api.liftcanary.com/v1/projects/web/flags/new_checkout/environments/production/toggle \
  -H "Authorization: Bearer $LIFTCANARY_TOKEN" -H "Content-Type: application/json" \
  -d '{"enabled": false}'

Saving safely with teammates#

Every save sends the version of the configuration you started from. If a teammate saved in the meantime, your save is refused with a prompt to reload instead of silently overwriting their change. API clients get the same protection with If-Match; see API overview.

Reading flags in code#

TypeScript
user.isEnabled("new_checkout");                        // boolean: is the feature on?
user.getVariable("new_checkout", "button_text", "Buy now"); // typed variable with a fallback
user.decide("new_checkout");                           // full decision: variation, rule, reason, variables

The website snippet has the same calls on window.liftcanary (isEnabled, variable, decide); React Native has hooks. Details per platform are in the SDK reference.

Archiving#

When a flag is fully rolled out, remove it from your code first, then archive it (Delete in the dashboard, DELETE …/flags/:flag in the API). Archived flags disappear from datafiles; code that still asks for one gets FLAG_NOT_FOUND and your fallback values.