Using Cloudflare Workers KV for Low‑Latency Feature Flags

The problem: keeping feature flags fast and consistent across the edge

When you roll out a new feature flag you want the decision to be available instantly to every request, no matter which Cloudflare POP serves it. Traditional approaches—central databases or external APIs—add round‑trip latency and can become a bottleneck under high traffic. You need a store that lives as close to the request as possible, scales with request volume, and gives you a simple API from within a Worker.

Why Workers KV fits the bill

Cloudflare Workers KV is a globally distributed key‑value store that runs on the same edge network as your Workers. Key characteristics that matter for feature flags:

• Read‑after‑write guarantee for requests handled by the same Worker instance – a write you make in a request is immediately visible to subsequent reads in that same invocation.
• Typical read latency under 10 ms when the POP that served the write also serves the read, making it suitable for sub‑100 ms decision making.
• Free tier includes 20 million reads per day and 1 GB of storage, with clear paid‑tier scaling.
• Managed via the Wrangler CLI, so you can preview changes locally before pushing to production.

Setting up a KV namespace with Wrangler

First, make sure you have a Cloudflare API token with the Account > Workers KV Storage > Edit permission. Then run the following commands in your project directory:

1. Create a namespace (you only need to do this once):

   wrangler kv:namespace create "FEATURE_FLAGS" --binding=FEATURE_FLAGS
   

   This outputs a namespace ID; keep it handy for later steps.

2. Add the binding to your wrangler.toml:

   [[kv_namespaces]]
     binding = "FEATURE_FLAGS"
     id = ""
   

3. Test locally with wrangler dev; the KV API is available via the binding.

Worked example: a feature‑flag Worker

The Worker below reads a flag named new‑ui from KV and returns a different HTML snippet based on its value. It demonstrates the read‑after‑write guarantee and shows how you would update the flag without redeploying the Worker.

export default {
  async fetch(request, env, ctx) {
    // Read the flag; default to "off" if the key does not exist
    const flag = await env.FEATURE_FLAGS.get("new-ui") ?? "off";
    
    if (flag === "on") {
      return new Response("New UI enabled", { headers: { "Content-Type": "text/html" } });
    } else {
      return new Response("Classic UI", { headers: { "Content-Type": "text/html" } });
    }
  }
};

To turn the flag on for all edge locations, run:

wrangler kv:key put --binding=FEATURE_FLAGS "new-ui" "on"

Because the write goes through the same API that the Worker uses, any subsequent request handled by the same Worker instance will see "on" immediately. Requests served by other POPs may still see the old value for a few seconds while the update propagates—this is the eventual consistency behavior.

Trade‑offs and limitations

• Eventual consistency: If you need strong consistency across all POPs instantly, KV is not the right choice; you would need to accept a short stale window or use a different store (e.g., Durable Objects with strong consistency).
• Size limits: Individual values cannot exceed 25 MB. Storing many large keys increases storage cost and can affect request latency.
• No multi‑key transactions: Concurrent updates to the same key require application‑level conflict resolution (e.g., last‑write‑wins or a version field).

Checking that your flag works as expected

After you have put a value, verify the read‑after‑write guarantee by making two requests in the same Worker invocation (you can do this locally with wrangler dev):

// In your Worker, after a put:
await env.FEATURE_FLAGS.put("test-key", "value");
const val = await env.FEATURE_FLAGS.get("test-key");
// val should be "value"

To observe propagation delay, deploy the Worker to two separate environments (e.g., preview and production) using wrangler publish --env preview and wrangler publish --env prod. Then, from a terminal, curl each endpoint repeatedly:

curl https://feature-flag-preview..workers.dev
curl https://feature-flag-prod..workers.dev

You should see the new value appear in the preview environment almost instantly, while the production endpoint may return the old value for a few seconds.

Actionable closing

If your application needs low‑latency, globally available configuration—such as feature flags, A/B test buckets, or short‑lived redirects—Cloudflare Workers KV offers a simple, cost‑effective starting point. Begin by creating a namespace, binding it in wrangler.toml, and using the get/put API within your Worker. Monitor usage in the Cloudflare dashboard to stay within free‑tier limits, and be aware of the eventual consistency window when you need immediate visibility across all POPs. With those considerations in mind, KV can become the reliable edge store that keeps your serverless logic fast and flexible.