Back to projects
Projectadvanced 7 steps ~80 min

Feature Flag Client

Build deterministic rollouts, ordered rule evaluation, a subscription store, and a useFlag hook with a live control panel.

What you'll build

A flag client and useFlag hook driving a gradual rollout you can change live from a control panel.

  • JavaScript
  • hashing
  • targeting rules
  • React hooks
  • subscriptions
Project briefrequirements and design decisions

Requirements

  • Percentage rollouts are sticky per user and monotonic when increased
  • Rules evaluate in order: kill switch, targeting, then percentage
  • Components re-render when a flag changes, without a page reload
  • Bootstrapped values prevent a flash of the wrong variant

Architecture decisions

  • FNV-1a hash of flagKey + userId for independent, deterministic buckets
  • Pure evaluate() function, easy to unit test
  • Subscription store consumed with useSyncExternalStore
  • Client receives evaluated values, never the full rule set

Stretch goals

  • Exposure events for experiment analysis
  • Stale-flag report: flags at 100% for 2+ weeks
  • Server-side evaluation in middleware

Production checklist

  • Safe defaults when the flag service is unreachable
  • Server-side enforcement for anything security-relevant
  • Owners and expiry dates for every flag

1What we're building

Feature flags let you deploy code dark and release it gradually: 1% of users, then 10%, then everyone, with a kill switch if anything goes wrong. You'll build the client side of a flag system:

  1. Deterministic bucketing: the same user always gets the same answer, and raising a rollout only adds users.
  2. Rule evaluation: kill switch → targeting rules → percentage rollout → default.
  3. A client store that holds evaluated flags and notifies subscribers when they change.
  4. A React useFlag hook built on useSyncExternalStore, with bootstrapped values so there's no flicker.
  5. A control panel that changes the rollout live, as an ops engineer would.

Security note: in production, rules are evaluated on the server and the browser receives only results. Flags hide UI; they don't enforce access. Anything sensitive must also be checked server-side.

Feature Flag Client project | Bloom