Blueprint: a real-time chat room

A real-time chat room where many people in the same room see each other's messages instantly. We use a WebSocket (a connection that stays open both ways) so the server can push new messages down without the browser asking again and again.

The trick is: who holds all those open connections and makes sure everyone in a room gets every message? The answer is a Durable Object (DO) — a single, always-there mini-server. We give every room its own Durable Object. A small Worker in front just routes each browser to the right room, and D1 (Cloudflare's SQL database) stores the message history.

There are four roles. Each has one clear job — keeping responsibilities separate is what makes the system easy to reason about.

Why is a Durable Object the natural "room"? Because the same room name always resolves to the exact same single instance, everywhere on Earth. That single instance becomes the one place where all the room's connections and state live — no locks, no message broker, no race conditions.

Live messages flow through the Durable Object in memory; the permanent copy lives in D1. We need just one table, messages, with a row per chat message. room_id ties each message back to the room it belongs to.

CREATE TABLE IF NOT EXISTS messages (
  id         INTEGER PRIMARY KEY AUTOINCREMENT,
  room_id    TEXT    NOT NULL,
  user       TEXT    NOT NULL,
  body       TEXT    NOT NULL,
  created_at INTEGER NOT NULL
);

CREATE INDEX IF NOT EXISTS idx_messages_room
  ON messages (room_id, created_at);

Here is the full life of one message — from a browser connecting, to the Durable Object broadcasting it to everyone and saving it to D1.

1. Create the project and a D1 database

   Scaffold a Worker, then create the D1 database that will hold the history. Note the database_id it prints — you paste it into config next.

   bashcontent_copyCopy

   npm create cloudflare@latest -- chat-room
   cd chat-room
   npx wrangler d1 create chat-history

2. Configure wrangler.jsonc

   Bind the Durable Object class (ROOMS), register a SQLite migration for it, and bind the D1 database (DB). The migration tells Cloudflare ChatRoom is a new SQLite-backed class.

   jsonccontent_copyCopy

   {
     "name": "chat-room",
     "main": "src/index.js",
     "compatibility_date": "2025-01-01",
     "durable_objects": {
       "bindings": [
         { "name": "ROOMS", "class_name": "ChatRoom" }
       ]
     },
     "migrations": [
       { "tag": "v1", "new_sqlite_classes": ["ChatRoom"] }
     ],
     "d1_databases": [
       { "binding": "DB", "database_name": "chat-history", "database_id": "<your-d1-database-id>" }
     ]
   }

3. Create the messages table

   Run the schema.sql from the data-model section against your D1 database so the messages table exists before you write to it.

   bashcontent_copyCopy

   npx wrangler d1 execute chat-history --remote --file=./schema.sql

4. Write the Worker (the router)

   The Worker only checks for a WebSocket upgrade, resolves the room's Durable Object by name with env.ROOMS.idFromName(room), and forwards the request. It re-exports ChatRoom so the runtime can find the class.

   jscontent_copyCopy

   import { ChatRoom } from "./chat-room.js";
   export { ChatRoom };
   
   export default {
     async fetch(request, env) {
       const url = new URL(request.url);
       const room = url.searchParams.get("room") || "lobby";
   
       // Only accept WebSocket upgrade requests
       if (request.headers.get("Upgrade") !== "websocket") {
         return new Response("Expected a WebSocket upgrade", { status: 426 });
       }
   
       // Resolve the ONE Durable Object for this room name
       const id = env.ROOMS.idFromName(room);
       const stub = env.ROOMS.get(id);
   
       // Forward the upgrade request to that room object
       return stub.fetch(request);
     },
   };

5. Write the Room Durable Object

   The DO completes the WebSocket handshake with acceptWebSocket (hibernation mode). The webSocketMessage handler runs on every incoming message: it saves one row to D1, then broadcasts to every socket returned by getWebSockets().

   jscontent_copyCopy

   import { DurableObject } from "cloudflare:workers";
   
   export class ChatRoom extends DurableObject {
     constructor(ctx, env) {
       super(ctx, env);
       this.ctx = ctx;
       this.env = env;
     }
   
     // Completes the WebSocket handshake and registers the socket
     async fetch(request) {
       const url = new URL(request.url);
       const room = url.searchParams.get("room") || "lobby";
   
       const pair = new WebSocketPair();
       const client = pair[0];
       const server = pair[1];
   
       // Hibernation: let the runtime hold the socket so the DO can sleep
       this.ctx.acceptWebSocket(server);
       server.serializeAttachment({ room });
   
       return new Response(null, { status: 101, webSocket: client });
     }
   
     // Runs whenever ANY connected client sends a message
     async webSocketMessage(ws, raw) {
       const { user, body } = JSON.parse(raw);
       const { room } = ws.deserializeAttachment();
       const created_at = Date.now();
   
       // 1) Persist to D1 history
       await this.env.DB
         .prepare("INSERT INTO messages (room_id, user, body, created_at) VALUES (?, ?, ?, ?)")
         .bind(room, user, body, created_at)
         .run();
   
       // 2) Broadcast to everyone connected to THIS room
       const payload = JSON.stringify({ user, body, created_at });
       for (const socket of this.ctx.getWebSockets()) {
         socket.send(payload);
       }
     }
   
     async webSocketClose(ws, code, reason, wasClean) {
       ws.close(code, "room closing socket");
     }
   }

6. Connect from the browser

   On the front end, open a WebSocket to the Worker with ?room=lobby, render each incoming message, and send the user's text as JSON. Use wss:// (the secure form) in production.

   htmlcontent_copyCopy

   <script>
     const room = "lobby";
     const ws = new WebSocket(`wss://chat-room.example.workers.dev/?room=${room}`);
   
     ws.addEventListener("open", () => console.log("connected to", room));
   
     ws.addEventListener("message", (event) => {
       const msg = JSON.parse(event.data);
       addLine(`${msg.user}: ${msg.body}`); // render into your chat list
     });
   
     // Call this when the user submits the chat box
     function send(user, text) {
       ws.send(JSON.stringify({ user, body: text }));
     }
   </script>

7. Deploy

   Publish to Cloudflare's network. Every distinct ?room= value you connect with automatically gets its own Durable Object.

   bashcontent_copyCopy

   npx wrangler deploy

Easy mistakes to avoid

• Forgetting to re-export the ChatRoom class from your Worker entry file — the runtime won't find it.
• Using ws:// instead of wss:// in production; browsers block insecure WebSockets on HTTPS pages.
• Doing heavy work inside webSocketMessage and blocking the broadcast — keep it: persist, then broadcast.
• Trusting the message body blindly — validate user and body before writing to D1.
• Expecting the DO's memory to last forever — it can hibernate, so treat D1 as the durable history.