In your appFeature flags
Feature flags
Ship code switched off, then turn it on for your team, a share of visitors or everyone, per environment, without a redeploy. Flags live in your project's Flags tab and your app checks them with `@useorbits/flags`.
How flags work
A flag is a named switch or value that your code checks. You manage flags in the project's Flags tab; your app checks them with the @useorbits/flags package.
Checks happen inside your app, not over the network. The package fetches your environment's flags once, answers every check from memory, and refreshes them in the background every few seconds. A change in the Flags tab reaches running deployments within seconds, with no redeploy.
Create a flag
- Open the project and choose Flags, then Create flag.
- Give it a key: lowercase letters, digits and single dashes, up to 48 characters, unique in the project, like
new-checkout. This is what your code checks. - Add a description (up to 120 characters) if it helps.
- Pick its Type:
- Boolean: on or off. Starts off in each environment, at a 100% rollout, with no rules, unless you turn it on.
- String or Number: serves a value. Give it a value for each environment.
- Press Create flag.
Owners, admins and members create, change and delete flags. Viewers can see them.
The key and type never change. To change either, make another flag. You can edit the description later.
Environments
Every flag has a setting for each of the three environments, and they're independent:
| Environment | Read by |
|---|---|
| Production | Production deployments |
| Preview | Preview deployments |
| Development | Your machine, with the development key (see local development) |
So you can turn a flag on in Preview, try it on a branch's preview, and only then turn it on in Production.
In each environment, a boolean flag has a switch (On or Off) and a rollout: the share of ids it's on for, from 1% to 100%. A string or number flag has a value.
Targeting rules
Rules come before the switch and the rollout: the first rule that matches decides. Each environment can have up to 20.
A rule is:
| Part | |
|---|---|
| What to check | An attribute your code passes to flag(): email, id, plan, country, or a path like user.plan |
| How to compare | equals, not_equals, one_of, starts_with, ends_with or contains. one_of takes several values separated by commas; the others take one |
| What a match gets | On or off for a boolean flag; a value for a string or number flag |
Comparisons ignore case. An attribute your code didn't pass matches nothing. For example, "Email ends with @kudi.ng, gets On" turns a new feature on for your own team only.
How a check is decided
For each check, in order:
- The first matching rule decides.
- Otherwise a boolean flag that's off is off.
- Otherwise a boolean flag is on for its rollout's share of ids. The same id always gets the same answer, and stays in as the share grows. Without an id, only a 100% rollout is on.
- A string or number flag serves its value.
The share is a stable hash of the flag's key and the id, so two flags at 25% don't pick the same quarter of your users.
Use flags in your code
$ npm install @useorbits/flagsEvery deployment gets its environment's key as ORBITS_FLAGS, and the API's address as ORBITS_API_URL, so there's nothing to configure. A variable you set yourself with the same name wins.
In server code (a Server Component, a route handler, an API, a worker):
import { flag } from "@useorbits/flags";
export default async function Checkout() {
const user = await currentUser();
if (await flag("new-checkout", { id: user.id, email: user.email })) {
return <OnePageCheckout />;
}
return <ClassicCheckout />;
}The second argument is the context that rules and rollouts read. String and number flags return their value. Pass a default for when the flag doesn't exist yet or Orbits can't be reached; a boolean flag's default is false:
const backend = await flag("search-backend", {}, "typesense");
const pageSize = await flag("page-size", {}, 20);To get every flag at once, such as to hand them all to a page:
import { flags } from "@useorbits/flags";
const all = await flags({ id: user.id });
// { "new-checkout": true, "search-backend": "typesense" }Flags are for server code. Checking flags in client components isn't available yet.
Options
The shared client reads ORBITS_FLAGS and ORBITS_API_URL. To set them yourself, call configure before the first check:
import { configure } from "@useorbits/flags";
configure({ key: process.env.MY_FLAGS_KEY, refreshMs: 10_000 });| Option | Default | |
|---|---|---|
key | ORBITS_FLAGS | The environment's key |
apiUrl | ORBITS_API_URL | Orbits' API |
refreshMs | 5000 | How old the flags may get before they're fetched again in the background |
report | true | Report which flags were checked, for "Seen in the last 24 hours" |
debug | false | Log fetches and reports |
For more than one key in a process, make your own client: new FlagsClient({ key }), then client.flag(...).
Local development
On your machine there's no deployment to hand you a key. Copy the Development key from the Flags tab (under On your machine) into .env.local:
ORBITS_FLAGS=ofl_…Your app then reads Development's flags. Without a key, every flag gets its default, and the package says so once in the console. Owners, admins and members can see the keys; viewers can't.
A key reads its environment's flags and reports checks, and does nothing else. Treat it like any other secret all the same. Keys can't be rotated one at a time yet.
A flag's page
Pick a flag to see each environment's setting and rules, and:
- History: every change, newest first (the last 50), with who made it.
- Seen in the last 24 hours: for each environment, how many checks there were and how many different ids they were for, as your deployments reported them.
Delete flag removes it everywhere. Your deployments stop getting it on their next refresh, and code that checks it gets the default it passes.
What the package calls
You don't need these to use flags; they're what @useorbits/flags does for you, in case you write your own client. Both take the environment's key as Authorization: Bearer ofl_…, not an API token.
GET /v1/flags/definitions
The environment's flags, for the package to evaluate:
{
"environment": "production",
"version": "…",
"flags": {
"new-checkout": {
"type": "boolean",
"on": true,
"rollout": 25,
"value": null,
"rules": [
{ "attribute": "email", "operator": "ends_with", "values": ["@kudi.ng"], "serve": true }
]
}
}
}Send If-None-Match with the last ETag and you get 304 while nothing has changed. That's how the package refreshes cheaply every few seconds. A wrong key is 401.
POST /v1/flags/exposures
About once a minute while flags are being checked, the package reports how many times each flag was checked and for which ids: up to 200 flags a report, 500 ids per flag. Each id is sent as the first 16 hex characters of its SHA-256, never as it was, so no user id leaves your app. Orbits keeps them by the hour for two days, for "Seen in the last 24 hours". Turn reporting off with configure({ report: false }).
Neither call counts against the API's rate limits.
From the CLI and the API
$ orbits flags create new-checkout --type boolean --description "One-page checkout"$ orbits flags set new-checkout --environment preview --on$ orbits flags set new-checkout --environment production --on --rollout 25$ orbits flags rules add new-checkout --environment production --attribute email \ --operator ends_with --values @kudi.ng --serve true$ orbits flags lsThe web app's calls are under /v1/teams/{team}/projects/{project}/flags: list, create, get, change the description, delete, set an environment (PUT .../flags/{flag}/environments/{environment} with on, rollout or value), and add, change or remove rules. GET .../flag-keys returns the three keys. See API › Flags.