Client-side vs. server-side feature flags, explained
Client-side vs. server-side feature flags comes down to where the user id resolves into a variant. A client-side flag evaluates in the browser or the device, after the SDK has loaded. A server-side flag evaluates on the server, before a response goes out. Same flag, different place to decide.
Most teams hit the tradeoff by accident rather than by choice. A client-side SDK typically downloads every flag’s full payload to the browser so it can decide locally, which means the console shows the flags for features that have not shipped yet. A server-rendered page can also disagree with the client-side bundle about which variant a user gets, so the UI flashes from one to the other on load. This guide covers how each model works, the security and flicker cost each one carries, and how deterministic assignment removes most of the tradeoff.
Key Takeaways
- Client-side feature flags evaluate in the browser after the SDK loads; server-side flags evaluate on the server before the response renders.
- A client-side SDK that ships every flag’s payload to the browser exposes unreleased feature names and targeting rules in plain JSON, visible in devtools.
- Mismatched client and server evaluation is the cause of feature-flag flicker: the server renders one variant, the client hydrates another.
- dif’s SDK computes the variant as a hash of the user id and the flag’s salt, so the same calculation runs on the server or in the browser and returns the same answer either way.
- A kill switch on a critical path should run server-side, because the server can block the request before a response ships at all.
What a client-side feature flag is
A client-side feature flag evaluates in the browser, in a mobile app, or on any device the SDK runs on. The variant is decided after the page or app has already loaded, typically from a config payload or a cached snapshot the SDK fetched earlier.
The appeal is speed to wire up: no server code to touch, every component can read a flag directly. The cost shows up in two places. First, a browser-evaluated SDK commonly ships the full flag configuration, including flags still in draft, because the client needs the rules to decide locally. Anyone who opens devtools can see what is coming next. Second, if the first render happens before the SDK resolves a variant, the user briefly sees a default, then the real one, which is the flicker problem covered below.
What a server-side feature flag is
A server-side feature flag evaluates on the server, before the response is built. The request already carries whatever identifies the user (a session, a cookie, a header), so the server resolves the variant once and renders accordingly. The client never receives flags it was not assigned, and a flag that is off never reaches the bundle at all.
The tradeoff runs the other way: a server-side-only flag cannot react to anything that only exists in the browser (a URL parameter the user just typed, a client-only feature detection), and a kill decided server-side still has to go through a deploy or a config push, not an instant client-side override.
The security problem: shipping every flag to the browser
Treat a flag payload the same way you’d treat an API response: never send data the client should not have. A browser-evaluated SDK that fetches the whole flag configuration is handing every visitor a list of in-progress feature names, audience rules, and sometimes rollout percentages, because the client has to have the rules to decide locally. OWASP’s API security guidance warns against this same pattern under a different name: sending a client more data than it needs because it’s easier than filtering server-side.
In dif, the flag file never leaves the repo. dif build compiles the active flags into a typed client and a context.json, but what ships to the browser is the compiled bucketing logic and the flag ids, not the frontmatter, the owner, or the rationale written in prose. Evaluating dif("new-checkout") in the browser does not require downloading a config listing every other flag in flight.
The flicker problem: when server and client disagree
Flicker happens when the server renders one variant and the client-side code computes a different one on hydration, so the UI visibly jumps. React warns against exactly this mismatch in its hydration docs, and it is a symptom of non-deterministic assignment: if evaluating the same flag for the same user can return two different answers, you will eventually see both of them in one page load, once on the server and once in the client-side re-render.
The fix is making assignment a pure function of the user id, computed identically wherever it runs. dif resolves the bucket as the first four bytes of SHA-256(salt || user_id), modulo 10,000, read against the flag’s weights. There is no state to disagree with between a render on the server and a render in the browser, because both sides run the same math on the same input and get the same output. How feature flags in React avoid flicker in practice covers the provider and hook side of this.
Why dif’s bucketing makes the split mostly disappear
Most of the client-side vs. server-side feature flags tradeoff exists because teams run two different evaluation paths: a server SDK that hits a database or an API, and a client SDK that fetches a cached config. Those two paths can drift, and drift is where flicker and over-exposure both come from.
dif runs one evaluation path. dif() from @dif.sh/sdk takes a user id and the flag id, hashes locally, and returns the variant, whether it’s called in a Node server, a SvelteKit server load function, or a browser bundle. There is no network call either way, so there is also no round trip to wait on before the first render. The flag the server picked is the flag the client will pick, because it’s the same deterministic calculation, not two systems kept in sync.
When you actually want one or the other
Deterministic, local evaluation removes most of the reason to pick a side, but two cases still call for choosing deliberately:
- A kill switch on a critical path belongs server-side. If a payment flow needs to stop in under a second, the server has to be the one that blocks the request, before any response (and any client-side code) ships. A browser-only flag can’t intercept a request that already left the server.
- Anything that depends on client-only context belongs client-side. A feature gated on a URL parameter, a viewport size, or a client-only capability check has no server-side signal to evaluate against, so it has to run after the page has loaded.
For everything in between, which is most flags, dif’s local evaluation runs correctly on either side without the usual cost of choosing.
Getting started
Install the SDK and call the same function on the server or in the browser:
npm install -g @dif.sh/cli
dif init
npm install @dif.sh/sdk
import { dif } from "@dif.sh/sdk";
const variant = dif("new-checkout", { userId: user.id });
The CLI reference covers dif validate, which runs in CI before any flag reaches either side of your stack, and the feature flags page shows the full workflow from file to running flag.
The client-side vs. server-side question is really a question about where assignment is computed and what gets exposed along the way. Server-side evaluation keeps unreleased flags off the client and handles a hard kill correctly. Client-side evaluation reacts to signals the server never sees. Deterministic bucketing, the same hash on both sides, is what keeps the two from disagreeing or over-sharing. Install the CLI and dif init to see which side your flags actually need to run on.
FAQ
What is the difference between client-side and server-side feature flags? A client-side flag evaluates in the browser or device after the app loads. A server-side flag evaluates on the server before the response is built. The practical difference is whether the client ever receives the raw flag configuration and whether the user sees a flash between two variants.
Are client-side feature flags a security risk? They can be, if the SDK ships the full flag configuration to the browser so the client can decide locally. That payload typically includes unreleased feature names and targeting rules, visible in devtools. Evaluating flags server-side, or compiling them so only the flag id and bucketing math ship to the client, avoids exposing the rest.
Why do feature flags flicker on page load? Flicker happens when the server renders one variant and the client computes a different one during hydration. It’s caused by non-deterministic or state-dependent assignment. Making assignment a pure function of the user id, computed the same way on both sides, removes the mismatch.
Should a kill switch be client-side or server-side? Server-side, for anything on a critical path. The server can block a request before a response goes out; a client-side flag can only change what renders after the page has already loaded.
Can one feature flag SDK handle both client-side and server-side evaluation? Yes, if assignment is computed locally and deterministically rather than fetched from a config service. dif’s SDK runs the same hash-based calculation in a server context or a browser bundle and returns the same variant for the same user id either way.