Deploy and run
Feature flags
Turn features on, off or on for a share of users from the dashboard, with no redeploy.
Feature flags let you ship code that's switched off, then turn it on for everyone, for a share of users, or off again if something goes wrong, without deploying again.
How to do it: in the project, open Webhooks and flags, add a flag and switch it on or off. Your app checks the flag with one small request.
"Add a flag called new-checkout, on for 10% of users."
Feature flags let you ship code that's switched off, then turn it on for everyone, for a percentage of users, or off again when something goes wrong, without a deploy.
Each project (and each environment, since environments are projects) has its own flags.
Add a flag
In the dashboard: open the project, choose Webhooks and flags, type a name like new_checkout and press Add a flag. New flags start off. Switch one on, and drag its slider to roll it out to a share of users.
Ask your agent:
"Add a flag new_checkout and turn it on for 10% of users."
With the API:
PUT /v1/projects/:id/flags{ "key": "new_checkout", "enabled": true, "rollout": 10, "description": "The one-page checkout" }Flag names are lowercase letters, digits, _, . and -, starting with a letter. A project can have 200.
Read flags in your app
Each project has a flag URL. Press Add CLI_FLAGS_URL to every app (or POST /v1/projects/:id/flags/install) to set it as a variable on every app; it applies on each app's next deploy.
Your app asks for one user's flags:
const r = await fetch(`${process.env.CLI_FLAGS_URL}?user=${encodeURIComponent(userId)}`);
const { flags } = await r.json();
if (flags.new_checkout) { /* the new checkout */ }{ "flags": { "new_checkout": true, "dark_mode": false } }- The same user always gets the same answer for a flag, so they don't flip between versions. Raising the rollout from 10% to 20% keeps the first 10% in.
- Without
?user=, a flag is on only when it's on for everyone. - Answers can be cached for 5 seconds, so changes reach your apps within seconds.
The URL contains a token. Anyone with it can read the flags (not change them), so keep it in a variable rather than in the browser. To replace it, press Make a new URL (or POST /v1/projects/:id/flags/rotate): the old URL stops working, and you update CLI_FLAGS_URL in your apps.