OrbitsDocs
esc
    Open Orbits
    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

    1. Open the project and choose Flags, then Create flag.
    2. 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.
    3. Add a description (up to 120 characters) if it helps.
    4. 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.
    5. 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:

    EnvironmentRead by
    ProductionProduction deployments
    PreviewPreview deployments
    DevelopmentYour 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 checkAn attribute your code passes to flag(): email, id, plan, country, or a path like user.plan
    How to compareequals, 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 getsOn 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:

    1. The first matching rule decides.
    2. Otherwise a boolean flag that's off is off.
    3. 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.
    4. 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

    Terminal
    $ npm install @useorbits/flags

    Every 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):

    tsx
    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:

    TypeScript
    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:

    TypeScript
    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:

    TypeScript
    import { configure } from "@useorbits/flags";
    
    configure({ key: process.env.MY_FLAGS_KEY, refreshMs: 10_000 });
    OptionDefault
    keyORBITS_FLAGSThe environment's key
    apiUrlORBITS_API_URLOrbits' API
    refreshMs5000How old the flags may get before they're fetched again in the background
    reporttrueReport which flags were checked, for "Seen in the last 24 hours"
    debugfalseLog 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:

    .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:

    JSON
    {
      "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

    Terminal
    $ 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 ls

    The 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.

    Was this page helpful?

    Updated