← Blog

Lightweight feature flag SDK: what 5 kB buys you

A lightweight feature flag SDK has no network call to make and no vendor client to load. dif’s SDK is 5 kB gzipped with zero dependencies, because a user’s variant is computed locally from a hash of their user id instead of fetched from a service.

Most flag SDKs are not lightweight. They bundle a client for an evaluation or streaming service, a local cache to survive a dropped connection, and reconnect logic to pick the connection back up. That is normal for a tool whose source of truth lives in a dashboard somewhere else. A flag SDK only gets small when it has nothing to call out to.

This post walks through what takes up the kilobytes in a feature flag SDK, how dif’s SDK stays at 5 kB, and what you give up to get there.

Key Takeaways

  • dif’s feature flag SDK is about 5 kB gzipped with zero dependencies, for browser and server.
  • The weight in a typical flag SDK comes from the evaluation or streaming client, not the flag logic itself.
  • dif computes a variant as the first four bytes of SHA-256(salt || user_id) mod 10,000, so there is nothing to fetch and nothing to cache.
  • Zero dependencies means zero transitive packages to audit, and none that can break under you on the next install.
  • The tradeoff: no persistent connection means a changed flag needs a new build, the same deploy-to-rollback cost as every other part of dif’s model.

What makes a feature flag SDK lightweight

A feature flag SDK does three things: hold the flag state, decide a variant for the current user, and report what happened. The third part, reporting, is a small HTTP call either way. The first two are where SDKs diverge.

A SaaS flag SDK usually holds a persistent connection (a WebSocket or SSE stream) so it can learn about a changed flag in real time, plus a local cache and reconnect logic for when that connection drops. That machinery, not the actual if statement it is guarding, is what makes the SDK heavy.

dif’s SDK skips all of it. There is no live connection to maintain, because the SDK does not need to be told the answer. It computes one.

Where the weight usually goes

Open the dependency tree of a typical feature-flag or experimentation SDK and you will find an event-stream client, a retry and backoff layer for that stream, and often a full HTTP client bundled in rather than using fetch. None of that is wasted code. It is doing real work: keeping a dashboard-hosted flag in sync with a running process.

The cost shows up twice. Once in the download: every extra kilobyte of JavaScript adds milliseconds to page load, the kind of delay a growth team notices in conversion numbers, not just in a bundle analyzer. And once in behavior: until that first stream connection resolves, the SDK does not know the real variant, which is the root of the flicker bug where the server renders one thing and the client swaps in another a moment later.

No network call: how dif keeps assignment local

dif removes the sync problem by removing the thing being synced. A flag’s weights are compiled into the SDK’s typed client at build time by dif build, and the variant itself is computed, not looked up:

import { dif } from "@dif.sh/sdk";

dif("checkout-cta-v2", {
  control: () => "Place order",
  variant_a: () => "Get it today",
});

Under the hood, that call hashes the flag’s salt with the user id using SHA-256 (the digest algorithm defined in NIST FIPS 180-4), takes the first four bytes of the digest as a big-endian integer, and reduces it mod 10,000 to pick a bucket from the compiled weights. Nothing is stored and nothing is fetched. The same user id produces the same bucket every time, on the server and in the browser. That is also why there is no flicker: there is nothing to reconcile between two sources of truth.

Zero dependencies, a smaller supply chain

@dif.sh/sdk ships with zero runtime dependencies:

npm view @dif.sh/sdk dependencies
# {}

Every dependency a package pulls in is code you did not write, running in your app, that can change under you on the next install. A flag SDK with zero dependencies has nothing in its own tree to audit, nothing to get a CVE against, and nothing to break because a transitive package shipped a bad patch release at 2 a.m.

The React and Svelte adapters (@dif.sh/react, @dif.sh/svelte) add a thin wrapper on top (a provider, a hook, server-load glue) but the core evaluation logic they call into is the same zero-dependency core.

What a 5 kB SDK does not give you

The honest cost of skipping the persistent connection: dif’s SDK has no way to push a changed flag to a running process. To change a weight, you edit the flag file and run dif build again, which means a new deploy. If your build takes ten minutes, that is how long it takes a flag change to reach production.

That is the same deploy-to-rollback tradeoff behind feature flags in git: rollback is a commit and a merge, not a toggle. For a payment path that needs a sub-second kill switch, a SaaS tool with a live connection is the right call for that one flag. For the rest, where the failure mode is “some users see the new thing a few minutes later than planned,” a small SDK with no open connection is the better trade.

Installing the lightweight feature flag SDK

npm install -g @dif.sh/cli
dif init
npm install @dif.sh/sdk

dif init scaffolds a dif/ directory and the generated client with no account and no API key. dif new drafts a flag, dif validate checks it, and dif build compiles it into the client the SDK you just installed actually reads. The SDK docs cover the React and Svelte adapters, and the feature flags page walks the full workflow.

A lightweight feature flag SDK is small because it has nothing left to call. For most teams running most flags, that is a better default than a heavier client holding a connection open just in case.

FAQ

Is a 5 kB feature flag SDK actually lighter than a typical flag SDK? Yes, measured against SDKs that bundle a streaming or evaluation-service client. dif’s SDK is about 5 kB gzipped because it has no persistent connection, local cache, or reconnect logic to ship; the variant is computed from a hash instead of fetched.

Does a lightweight feature flag SDK still support A/B tests? Yes. A flag and an experiment use the same dif() call and the same local bucketing; an experiment just holds a split instead of ramping to 100%. See A/B testing for developers.

Why does dif’s feature flag SDK have zero dependencies? Because there is nothing for a dependency to do. There is no HTTP polling, no stream client, and no cache to maintain, so the SDK is the hashing and bucketing logic plus the typed client dif build generates.

Does a small feature flag SDK mean I lose real-time flag updates? Yes, and that is the real tradeoff. A changed weight needs a new dif build and a deploy to reach production, the same cost as any other change in dif’s git-native model.

Is the SDK size the same on the server and in the browser? Yes. The core package runs in both environments with the same zero-dependency bucketing logic; only the adapters (@dif.sh/react, @dif.sh/svelte) differ by where they are used.