Using Cloudflare Workers KV for Global Feature Flags

The problem: sharing mutable state at the edge

When you roll out a new UI or adjust a rate‑limit, you need every Worker instance—no matter where it runs—to see the same flag value instantly. Managing an external database adds latency and operational overhead, while hard‑coding values forces a full redeploy for each change.

Thesis: Cloudflare Workers KV gives you a low‑latency, eventually consistent store that lets Workers read flags with sub‑millisecond delay while keeping write complexity manageable.

How KV works under the hood

Cloudflare’s edge is split into many data centers. A KV namespace is partitioned across these centers; each key lives on a subset of nodes determined by a hash of the key name. Writes are sent to the primary partition and then propagated asynchronously to replicas. Reads hit the nearest replica, which is why they are typically sub‑millisecond, but they may return a stale value for a few seconds until propagation finishes. The conflict resolution policy is last‑writer‑wins.

Worked example: a global counter for a feature flag

Below is a minimal Worker that increments a counter stored in KV, reads the current value, and decides whether to serve a new UI. The code assumes you have already created a KV namespace and bound it to the variable FEATURE_KV in your wrangler.toml.

export default {
  async fetch(request, env, ctx) {
    // Increment the counter (write)
    let current = await env.FEATURE_KV.get('flag:counter')
    let num = current ? parseInt(current, 10) + 1 : 1
    await env.FEATURE_KV.put('flag:counter', String(num))

    // Read the latest value (may be stale)
    let value = await env.FEATURE_KV.get('flag:counter')
    let enabled = value && parseInt(value, 10) >= 100

    const body = enabled
      ? 'New UI enabled'
      : 'Classic UI'
    return new Response(body, { headers: { 'Content-Type': 'text/html' } })
  }
}

To test locally:

1. Run wrangler dev in the project directory. This starts a local server on http://127.0.0.1:8787 and uses your local KV preview namespace.
2. Send requests with curl http://127.0.0.1:8787 and observe the response toggle after roughly 100 increments.
3. When ready, publish with wrangler publish (requires your Cloudflare API token with Account.Workers Scripts:Edit permission).

After publishing, you can verify the value in the Workers dashboard → KV → your namespace → flag:counter. The dashboard shows the current stored value and the time of the last update, letting you confirm propagation.

Trade‑offs and limitations

• Eventual consistency: Reads may return stale data for up to a few seconds. For feature flags this usually means a brief window where some users see the old UI while others see the new one.
• Write latency and throttling: Each put incurs higher latency (typically tens of milliseconds) because the update must propagate. High‑frequency writes to the same key can exceed the namespace write‑throughput quota and result in 429 Too Many Requests errors.
• Size limits: Individual records are capped at 128 KB; larger blobs must be stored elsewhere (e.g., R2) and only a reference kept in KV.

If you need strong consistency (e.g., a counter that must never lose an increment), consider using Cloudflare Durable Objects instead of KV for that specific key.

Actionable checklist

1. Create a KV namespace in the Cloudflare dashboard or with wrangler kv:namespace create FEATURE_KV.
2. Add the binding to wrangler.toml:

   [kv_namespaces]
   binding = "FEATURE_KV"
   id = "<your‑namespace‑id>"
   

3. Implement the helper functions (get, put, optional delete) as shown in the example.
4. Monitor KV request metrics in the Workers dashboard (reads, writes, errors) and watch for throttling spikes.
5. If you observe high write latency or errors, shard the key by appending a hash or random suffix (e.g., flag:counter:${shardId}) and aggregate reads across shards.
6. Set a reminder to review the flag’s TTL or expiration policy; KV does not expire keys automatically, so you must delete or overwrite them when no longer needed.

By following these steps you can safely roll out feature flags globally with minimal latency, while understanding and mitigating the consistency trade‑offs inherent to KV.