Feature flags

Feature flags let you ship code dark and turn it on without a deploy. Today each flag has a global on/off and a global default variant — every user who fetches the flag set sees the same answer. Per-user targeting (segment-scoped flags, sticky A/B variants) is on the roadmap; the SDK contract is already shaped for it so client code won't need to change when it lands.

Two flag types:

• Boolean flags — global on / off. Read with useFlag(name) or flags.fetch().then(...).
• Variant flags — return a string (e.g. 'control' / 'short' / 'long'). Today the variant is the same for every user, so use these for kill-switched rollouts and config-as-flag, not as A/B traffic splitters yet.

Each flag can also carry a payload JSON value — useful for config-driven feature gates ({ "max_items": 25 }).

Quick start

import { Amba } from '@layers/amba-web';
 
const flags = await Amba.flags.fetch();
const newUi = flags.find((f) => f.name === 'new_ui')?.enabled ?? false;
const copy = flags.find((f) => f.name === 'signup_copy')?.variant ?? 'control';

Operations

fetch()

Returns the full flag set for this project. Each entry has the shape:

{
  name: 'new_onboarding',     // flag name
  enabled: true,               // boolean on/off (global)
  variant: 'short',            // optional variant tag (global)
  payload: { max_items: 25 },  // optional, attached JSON config
}

The SDK caches the response for the lifetime of the session — subsequent fetch() calls within ~60 seconds return the cache. Force a refresh by signing the user out and back in (e.g. after a flag-config change).

Today every signed-in user receives the same flag set. When per-user targeting ships, the response shape stays the same — the values just start varying by user, and the SDK cache will key on the user.

React hooks

useFlag(name) returns a boolean. useVariant(name) returns the variant string (or null if unset / not loaded).

import { useFlag, useVariant } from '@layers/amba-react';
 
function NewFeature() {
  const enabled = useFlag('new_feature');
  if (!enabled) return null;
 
  const layout = useVariant('new_feature_layout'); // 'horizontal' | 'vertical' | null
  return layout === 'horizontal' ? <Horizontal /> : <Vertical />;
}

Both hooks default to safe values (false / null) while the initial fetch is in flight — render without an explicit loading guard.

Patterns

Gate render at module scope

For flags that gate large slabs of the UI, prefer fetching once at app start and stashing the result:

let flagsCache: Awaited<ReturnType<typeof Amba.flags.fetch>> | null = null;
 
export async function getFlag(name: string): Promise<boolean> {
  flagsCache ??= await Amba.flags.fetch();
  return flagsCache.find((f) => f.name === name)?.enabled ?? false;
}

Config-driven gates

For A/B tests with parameterized behavior, attach a payload to the variant in the console and read it on the client:

function PaginatedList() {
  const flags = await Amba.flags.fetch();
  const flag = flags.find((f) => f.name === 'pagination_size');
  const limit = (flag?.payload as { limit?: number })?.limit ?? 20;
  const { data } = await Amba.collections.find('posts', { limit });
  return <List items={data} />;
}

Server-side parity

Server functions can read the same flag set via ctx.flags.fetch() (or amba.flags.fetch() from a Node server). Useful for gating server logic on the same answer as the UI:

// Server function
export default defineFunction(async (req, ctx) => {
  const flags = await ctx.flags.fetch();
  const newPipeline = flags.find((f) => f.name === 'new_processing_pipeline')?.enabled ?? false;
  return newPipeline ? newImpl() : oldImpl();
});

Limits

• Flag count: up to 100 flags per project visible to a single fetch.
• Variant count: up to 8 variants per multi-variant flag (control + 7 treatments is a common ceiling).
• Payload size: up to 8 KB JSON per flag.
• Cache TTL: ~60 seconds per session, then a server round-trip on next fetch(). To deliberately re-fetch (e.g. after toggling a flag), sign the user out and back in.

Reference

• Client API — flags — endpoint reference.
• Auth feature — prerequisite.
• Config feature — for non-flag remote config bundles.
• Per-platform quickstarts: Web, Node, iOS, Android, Flutter, Unity.