How to Architect a Frontend Feature Flag System

Feature flags serve four distinct purposes. Release flags allow merging incomplete code to main without exposing it to users, enabling trunk-based development. Experiment flags enable A/B testing to measure the impact of UI changes on conversion metrics. Ops flags allow disabling expensive features instantly during incidents without deploying new code. Permission flags show different functionality to different user segments like beta users or premium subscribers.

Flags can be evaluated on the server or the client. Server-side evaluation happens before the HTML is sent to the browser, preventing any flash of the wrong variant and making flags invisible to users. Client-side evaluation happens in the browser after loading the flag configuration, which can cause a flash of the default state before the flag resolves. For flags controlling major UI sections, prefer server-side evaluation. Client-side evaluation is acceptable for low-visibility experiments.

Create a centralized Flag Provider component that fetches the complete flag configuration for the current user from your flag service on application load. Store the resolved flag values in React Context. Components consume flag values through a useFlag hook that takes a flag key and returns the current variant. This architecture means no component knows or cares where flag values come from, making it trivial to switch flag providers.

In an A/B experiment, a user must always see the same variant across sessions and devices. Consistent bucketing assigns users to variants by hashing a stable identifier like their user ID against the flag configuration. The same user ID always produces the same hash and therefore the same bucket assignment. For logged-out users, generate a stable anonymous ID stored in a cookie. Never use random assignment per page load as it creates an inconsistent flickering experience.

Without discipline, flags accumulate indefinitely. Each flag adds cognitive overhead and testing complexity. Every flag must be created with a defined expiration date or removal condition. Release flags should be removed within two weeks of the feature fully launching. Experiment flags are removed after the experiment concludes and a winner is declared. Implement a CI check that fails when code references a flag marked as expired, forcing the team to clean it up.

QA engineers and developers need to force specific flag variants to test all code paths without changing the production configuration. Implement URL parameter overrides that allow appending flag keys and variant values to any URL to force that variant for the current session. Implement a developer tools panel that shows all active flags and allows toggling them locally. Overrides must only work in non-production environments or for users with a developer role.

An experiment produces meaningless results if you cannot accurately determine which users were exposed to which variant. Log a flag exposure event every time a flag is evaluated and the user actually sees content influenced by the flag value. Include the flag key, variant, user ID, and timestamp. The exposure event, not the variant assignment, defines the experiment population. Users assigned to a variant but never exposed must be excluded from the analysis.

Flag configuration must load before rendering flag-dependent UI to prevent flickering between variants. Display a loading skeleton for the entire application during the initial flag fetch. Set aggressive caching headers on the flag endpoint so the configuration is served from CDN cache within milliseconds. Include default flag values in the application bundle as a fallback so the application renders correctly even if the flag service is unavailable.