Use feature flags

A feature flag is a named switch your website reads from CMS Orbit. You build a feature into the website behind it and release the code as usual. Whether visitors see the feature is then decided in CMS Orbit, under Configuration › Feature flags, without a new release. Each environment has its own switch, so a feature can be on in Staging for testing and off in Production until it is ready.

Typical uses:

• Launch on a set day. Release the new booking form a week early, switched off, and switch it on when marketing is ready.
• Test in Staging first. Switch it on in Staging only and check it on the Staging website.
• Turn something off quickly. If a feature misbehaves, switch it off and the website stops showing it within seconds.

A flag is a plain on or off for the whole environment. It doesn't show different things to different visitors, and it isn't a place for settings or text; use content for those.

1Add the flag in CMS Orbit

1. Open Configuration › Feature flags.
2. Type the flag's name, such as new-booking-form, and choose Add flag. Names use lower-case letters, numbers and hyphens.
3. The flag is added to every environment, switched off.

Agree the name with whoever writes the website code: the code checks for exactly that name. Changing switches needs the right to manage environments, which Developers and Administrators have.

2Check the flag in your website

Read the flags with the SDK. getFlags() answers with every flag of the environment the key belongs to, as { "new-booking-form": false }. A flag that doesn't exist reads as undefined, so treat anything but true as off.

1import { cms } from '@/lib/cms'23export default async function TripPage() {4  const flags = await cms.getFlags()5  return flags['new-booking-form'] === true ? <NewBookingForm /> : <BookingForm />6}

In a client component, read the flags on the server and pass on what it needs:

const flags = await cms.getFlags()return <SiteHeader showSearch={flags['header-search'] === true} />

Without the SDK, ask the delivery API:

curl 'https://api.bifrostorbit.com/cms/v1/flags' -H 'Authorization: Bearer cms_pk_…'

{ "data": { "flags": { "new-booking-form": false, "header-search": true } } }

3Refresh the website when a switch changes

Every change to a flag sends the flags.changed webhook. With the SDK's revalidate handler (see Refresh the website when content changes), it refreshes the flags, cache tag cms:flags, and pages that read them show the change on their next request.

New webhooks are subscribed to Feature flag changed already. For a webhook made earlier, open Configuration › Webhooks, edit it and tick Feature flag changed. Without it, a change shows once the page's cache runs out.

4Switch it on

1. Release the website with the check in it, while the flag is still off everywhere. Nothing changes for visitors.
2. In Configuration › Feature flags, turn the flag on in Staging and check the feature on the Staging website.
3. When it is ready, turn it on in Production.

To turn it off again, switch it off. The website goes back to the old behaviour without a release.

5Clean up

Once a feature is on for good, take the check out of the code and release the website. Then remove the flag with the bin next to it. Remove it only after the check has gone: a website that still checks a removed flag reads it as off.

What gets recorded

Every flag added, switched or removed is in Organisation › Audit log, with who did it and in which environment. Flags are also sent to Orbit Exchange as cms.flags.changed, with the environment's flags as they now are.