Docs menu

Deploy and run

Feature flags

Turn features on, off or on for a share of users from the dashboard, with no redeploy.

Explain it

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:

API
PUT /v1/projects/:id/flags
JSON
{ "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:

JavaScript
const r = await fetch(`${process.env.CLI_FLAGS_URL}?user=${encodeURIComponent(userId)}`);
const { flags } = await r.json();
if (flags.new_checkout) { /* the new checkout */ }
JSON
{ "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.