Durable Objects in Blaze: Stateful Workers at the Edge

Access Cloudflare Durable Objects from Blaze via req.env. Forward requests to named DO instances for stateful logic like chat rooms and presence.

Durable Objects are single-instance, stateful Workers that Cloudflare routes all traffic for a given ID to the same physical server — making them ideal for chat rooms, presence systems, collaborative editing, game sessions, and any use case where you need globally consistent state without an external database. Blaze gives you access to your Durable Object namespaces via req.env using the same type-safe pattern as every other binding, so forwarding a request to a specific DO instance is just a few lines of code.

Configure the binding

1. Declare the Durable Object in wrangler.toml

   wrangler.toml

   [[durable_objects.bindings]]
   name       = "ROOMS"
   class_name = "ChatRoom"
   
   # The migration tells Cloudflare to create the DO class
   [[migrations]]
   tag         = "v1"
   new_classes = ["ChatRoom"]
   
2. Define the Env type

   src/types/env.ts

   export type Env = {
     ROOMS: DurableObjectNamespace;
     // ...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.ROOMS is fully typed as DurableObjectNamespace in every handler
   

The Durable Object class (ChatRoom in the example above) must be defined and exported separately in your Worker entry point. The class must extend DurableObject and implement a fetch(request) method. Blaze handles the HTTP routing layer; your DO class handles the stateful logic.

src/durable-objects/chat-room.ts

export class ChatRoom {
  state: DurableObjectState;

  constructor(state: DurableObjectState) {
    this.state = state;
  }

  async fetch(request: Request): Promise<Response> {
    // Handle WebSocket upgrades, messages, presence, etc.
    return new Response("ChatRoom ready");
  }
}

Then re-export it from your entry point:

src/index.ts

export { ChatRoom } from "./durable-objects/chat-room";
export default { fetch: app.fetch };

Getting a DO instance

Every Durable Object instance is identified by a DurableObjectId. Derive an ID in one of two ways:

Method	When to use
idFromName(name)	Stable, human-readable key (e.g. room slug, user ID). Same name always resolves to the same instance.
idFromString(hexId)	Re-hydrate a previously generated ID stored in a database or passed as a URL parameter.

app.get("/rooms/:id", async (req, res) => {
  // idFromName — always routes to the same instance for a given room name
  const doId = req.env.ROOMS.idFromName(req.params.id);

  // idFromString — reconstruct an ID you stored earlier
  // const doId = req.env.ROOMS.idFromString(req.params.id);

  const stub = req.env.ROOMS.get(doId);

  // stub is a DurableObjectStub — call fetch() to communicate with the instance
  const response = await stub.fetch(new Request("https://do-internal/info"));
  const info = await response.json();

  res.json(info);
});

Forwarding requests to a DO

The most common pattern is to forward the entire incoming request — including a WebSocket upgrade — directly to the Durable Object. The DO handles the upgrade and owns the persistent connection state.

app.get("/rooms/:id/ws", async (req, res) => {
  // Derive a stable ID from the room name so all clients for the
  // same room always land on the same DO instance
  const doId = req.env.ROOMS.idFromName(req.params.id);
  const stub  = req.env.ROOMS.get(doId);

  // Forward the raw WebSocket upgrade request to the DO
  const response = await stub.fetch(req.raw);

  // Pass the DO's response (101 Switching Protocols) back to the client
  res.raw(response);
});

You can forward any request type — REST calls, streaming, RPC — not just WebSocket upgrades:

app.post("/rooms/:id/message", async (req, res) => {
  const doId = req.env.ROOMS.idFromName(req.params.id);
  const stub  = req.env.ROOMS.get(doId);

  const body = await req.json<{ text: string; author: string }>();

  const doResponse = await stub.fetch(
    new Request("https://do-internal/message", {
      method:  "POST",
      headers: { "Content-Type": "application/json" },
      body:    JSON.stringify(body),
    })
  );

  const result = await doResponse.json();
  res.status(doResponse.status).json(result);
});

Named instances

idFromName() is the building block for stable, long-lived DO instances tied to application entities. Use a consistent naming scheme so every part of your application resolves to the same instance for a given entity.

// One DO instance per user — coordinates their real-time presence
app.get("/users/:userId/presence", async (req, res) => {
  const doId = req.env.ROOMS.idFromName(`user:${req.params.userId}`);
  const stub  = req.env.ROOMS.get(doId);

  const presence = await stub.fetch(
    new Request("https://do-internal/presence")
  );

  res.send(await presence.text());
});

// One DO instance per org × document — coordinates collaborative edits
app.get("/docs/:docId/collab", async (req, res) => {
  const doId = req.env.ROOMS.idFromName(`doc:${req.params.docId}`);
  const stub  = req.env.ROOMS.get(doId);

  const response = await stub.fetch(req.raw);
  res.raw(response);
});

Named Durable Objects created with idFromName() are permanent — they are not garbage-collected until you explicitly delete them via the Cloudflare API or Wrangler. Design your naming scheme carefully; a new DO instance is provisioned the first time an ID is accessed, and storage costs accrue from that point forward.