Using Cloudflare KV Namespaces in Blaze via req.env

Access Cloudflare KV namespaces directly via req.env in any Blaze handler. Read, write, list, and delete key-value pairs with full TypeScript types.

Blaze injects every KV namespace declared in your wrangler.toml directly onto req.env with full type safety. Once you add the binding to your Env type and pass it to createApp<Env>(), every handler in your application can read, write, list, and delete keys — no extra setup, no manual passing of the namespace, no casting.

Configure the binding

Start by declaring the namespace in wrangler.toml, then mirror it in your Env type.

1. Add the namespace to wrangler.toml

   wrangler.toml

   [[kv_namespaces]]
   binding = "CACHE"
   id      = "abc123def456abc123def456abc123de"
   
2. Define the Env type

   src/types/env.ts

   export type Env = {
     CACHE: KVNamespace;
     // ...other bindings
   };
   
3. Pass Env to createApp

   src/index.ts

   import { createApp } from "blaze";
   import type { Env } from "./types/env";
   
   const app = createApp<Env>();
   // req.env.CACHE is now fully typed as KVNamespace in every handler
   

Reading from KV

Use req.env.CACHE.get(key, { type: 'json' }) to retrieve a stored value and let Blaze handle deserialization. The method returns null when the key does not exist, so always guard against a missing value before responding.

app.get("/cache/:key", async (req, res) => {
  const value = await req.env.CACHE.get(req.params.key, { type: "json" });

  if (value === null) {
    return res.status(404).json({ error: "Key not found" });
  }

  res.json(value);
});

The type: 'json' option tells the KV runtime to deserialize the stored string automatically. Other supported types are 'text' (default), 'arrayBuffer', and 'stream'.

Writing to KV

Use req.env.CACHE.put(key, value, options) to store a value. Pass expirationTtl (seconds from now) or expiration (Unix timestamp) to set a TTL — keys without a TTL persist indefinitely.

app.put("/cache/:key", async (req, res) => {
  const body = await req.json<Record<string, unknown>>();

  await req.env.CACHE.put(
    req.params.key,
    JSON.stringify(body),
    { expirationTtl: 3600 } // expires in 1 hour
  );

  res.status(201).json({ ok: true, key: req.params.key });
});

KV put operations are strongly consistent within the same Cloudflare datacenter but eventually consistent globally. Expect propagation delays of up to 60 seconds across regions.

Listing keys

req.env.CACHE.list() returns up to 1,000 keys at a time. Use the prefix option to scope the listing, and check list_complete to detect when there are more pages to fetch.

app.get("/cache", async (req, res) => {
  const prefix = req.query.get("prefix") ?? undefined;

  const { keys, list_complete, cursor } = await req.env.CACHE.list({
    prefix,
    limit: 100,
  });

  res.json({
    keys: keys.map((k) => ({ name: k.name, expiration: k.expiration })),
    list_complete,
    cursor: list_complete ? undefined : cursor,
  });
});

Deleting keys

req.env.CACHE.delete(key) removes a key immediately. Deleting a key that does not exist is a no-op — no error is thrown.

app.delete("/cache/:key", async (req, res) => {
  await req.env.CACHE.delete(req.params.key);
  res.status(204).send();
});

Fire-and-forget writes

When a KV write does not need to complete before you send a response, hand the promise to req.ctx.waitUntil(). Blaze will keep the Worker alive to finish the write without blocking the response returned to the client.

app.post("/events", async (req, res) => {
  const event = await req.json<{ type: string; data: unknown }>();

  // Respond immediately — the write happens in the background
  res.status(202).json({ status: "accepted" });

  req.ctx.waitUntil(
    req.env.CACHE.put(
      `event:${crypto.randomUUID()}`,
      JSON.stringify(event),
      { expirationTtl: 86400 }
    )
  );
});

KV is an excellent store for configuration values and feature flags that change infrequently. Because Cloudflare isolates can persist across multiple requests within the same datacenter, you can read a flag once per isolate startup and cache it in a module-level variable — dramatically reducing KV read costs for high-traffic workers.

// Module-level cache — populated once per isolate
let featureFlags: Record<string, boolean> | null = null;

app.use(async (req, _res, next) => {
  if (!featureFlags) {
    featureFlags =
      await req.env.CACHE.get<Record<string, boolean>>("feature-flags", {
        type: "json",
      }) ?? {};
  }
  next();
});