Feature flags

Read your workspace's feature flags to switch parts of your app on and off, or change text and settings, without publishing a new release. Your app reads the flags of the environment it runs in, so dev and prod can differ.

Read a flag

The starter kit's useFlag hook returns a flag's value, or your fallback until it loads:

import { useFlag } from "./lib/flags";

export function Banner() {
  const show = useFlag("promo-banner", false);
  const text = useFlag("promo-text", "Welcome");
  return show ? <div className="banner">{text}</div> : null;
}

The hooks check for changes every 60 seconds, so a flag you change shows up within a minute without a reload.

Without the starter kit

const env = window.__GF_ENVIRONMENT_ID__;
const res = await fetch(
  `${window.__GF_CONTROLPLANE_URL__}/v1/workspaces/${window.__GF_WORKSPACE_ID__}/flags/runtime` +
    (env ? `?environment_id=${encodeURIComponent(env)}` : ""),
  { headers: { Authorization: `Bearer ${await window.__GF_GET_ACCESS_TOKEN__()}` } },
);
const { flags } = await res.json(); // { "promo-banner": true, "promo-text": "Welcome" }

Change a flag

Your app can only read flags. Change them in the Client Portal under Build → Feature flags, or with the CLI:

gf flags set promo-banner true -e prod

Good to know

• Flags aren't secret. Every signed-in user with a role can read every flag. Keep API keys in Secrets.
• Users need a role. A signed-in user without a role in your site gets 403.
• Locally, npm run dev reads the dev environment's flags. To read another environment, set VITE_GF_ENVIRONMENT_ID=<environment-id> in .env.local. With npm run dev:fixtures you get your fallbacks.

Next steps

• Feature flags — create flags and promote them between environments.