Feature Flags in the Client

• `loading` — the value is not known. Render a placeholder, or the branch you would default to, but decide which on purpose.
• `resolved` from the service — the real assignment. The only state that should produce an exposure event.
• `resolved` from cache — a previous session's value. Fine, and it means a kill switch has not reached this client yet.
• `resolved` from default — the service could not be reached. The most important state to get right and the least often tested.
• Frozen — the value this unit of work will use regardless of what happens next, which is what keeps one screen on one branch.

1type FlagState<T> =
2  | { status: 'loading' }
3  | { status: 'resolved'; value: T; source: 'service' | 'cache' | 'default' }
4 
5// Defaults live with the flag definition, not at the call site,
6// and they answer one question: what is correct when the flag
7// service is unreachable?
8const FLAGS = {
9  newCheckout:      { default: false, critical: false },
10  euPricingRules:   { default: true,  critical: true  }, // legally required: fail on
11  experimentalSort: { default: false, critical: false },
12} as const
13 
14// Read once when the route is entered; hold it for the whole flow.
15// A checkout that re-reads the flag between steps is a checkout
16// that can change design halfway through.
17function useRouteFlag<K extends keyof typeof FLAGS>(key: K) {
18  const frozen = useRef<FlagState<boolean>>({ status: 'loading' })
19  const live = useFlagClient(key)
20  if (frozen.current.status === 'loading' && live.status === 'resolved') {
21    frozen.current = live
22  }
23  return frozen.current
24}
25 
26// At the call site the third state is unavoidable — which is the point.
27const flag = useRouteFlag('newCheckout')
28if (flag.status === 'loading') return <CheckoutSkeleton/>
29return flag.value ? <NewCheckout/> : <LegacyCheckout/>

source is not decoration. "This user got the default because the SDK timed out" and "this user was deliberately assigned false" are different facts, and only one of them is evidence in an experiment (Analytics Events That Answer a Question).

caveat The maybe rows depend on what else is on the page: whether the flipped subtree is inside a containment boundary, whether it is already promoted to its own layer, and whether anything after it in flow is size-dependent. Measure the actual change in the Performance panel rather than reasoning from the property name (CSS Containment).

• First paint: OFF branch — the user can read it and start reaching for a control
• Flag request — a third party, on a network you do not control
• Layout + paint: ON branch — the flip — content moves under the pointer
• — server-evaluated: first paint is already correct — no second branch, no flip, no reflow

The gap between the first paint and the flip is the entire problem, and it widens exactly where you have least control: a slow network, a cold connection to the flag vendor, or a device slow enough that the re-render itself is visible.

// "Only enterprise customers can export."
if (flags.enterpriseExport) {
  return <ExportButton/>
}
return null

// The user edits the cached flag payload, or calls
//   POST /api/reports/export
// directly — the path is in the bundle they downloaded.
// Nothing in this code was ever a boundary.

// The flag decides whether the feature exists for this cohort.
// The server decides, per request, whether this user may export
// this report — and says so in the response it already sends.
if (!flags.exportRedesign) return <LegacyExport/>

return report.can.export
  ? <ExportButton/>
  : <ExportButton disabled reason={report.can.exportDeniedBecause}/>

// POST /api/reports/:id/export re-checks authorization
// regardless of what the client rendered. The UI is a
// convenience; the check is the boundary.

The two booleans have different owners and different failure consequences. Rollout state is a product decision that may safely be wrong; authorization is a security decision that must be enforced where the user cannot reach it, which is never the browser (Authorization-Aware UI).