Rules of Durable Objects
- When to use Durable Objects
  - Use Durable Objects for stateful coordination, not stateless request handling
- Design and sharding

Rules of Durable Objects

Last updated Oct 18, 2026 Durable Objects provide a powerful primitive for building stateful, coordinated applications. Each Durable Object is a single-threaded, globally-unique instance with its own persistent storage. Understanding how to design around these properties is essential for building effective applications.

This is a guidebook on how to build more effective and correct Durable Object applications.

When to use Durable Objects

Use Durable Objects for stateful coordination, not stateless request handling

Workers are stateless functions: each request may run on a different instance, in a different location, with no shared memory between requests. Durable Objects are stateful compute: each instance has a unique identity, runs in a single location, and maintains state across requests.

Use Durable Objects when you need:

Coordination — Multiple clients need to interact with shared state (chat rooms, multiplayer games, collaborative documents)
Strong consistency — Operations must be serialized to avoid race conditions (inventory management, booking systems, turn-based games)
Per-entity storage — Each user, tenant, or resource needs its own isolated database (multi-tenant SaaS, per-user data)
Persistent connections — Long-lived WebSocket connections that survive across requests (real-time notifications, live updates)
Scheduled work per entity — Each entity needs its own timer or scheduled task (subscription renewals, game timeouts)

Use plain Workers when you need:

Stateless request handling — API endpoints, proxies, or transformations with no shared state
Maximum global distribution — Requests should be handled at the nearest edge location
High fan-out — Each request is independent and can be processed in parallel

index.jsjs

import { DurableObject } from "cloudflare:workers";

// ✅ Good use of Durable Objects: Seat booking requires coordination
// All booking requests for a venue must be serialized to prevent double-booking
export class SeatBooking extends DurableObject {
    async bookSeat(seatId, userId) {
        // Check if seat is already booked
        const existing = this.ctx.storage.sql
            .exec("SELECT user_id FROM bookings WHERE seat_id = ?", seatId)
            .toArray();

if (existing.length > 0) {
            return { success: false, message: "Seat already booked" };
        }

// Book the seat - this is safe because Durable Objects are single-threaded
        this.ctx.storage.sql.exec(
            "INSERT INTO bookings (seat_id, user_id, booked_at) VALUES (?, ?, ?)",
            seatId,
            userId,
            Date.now(),
        );

return { success: true, message: "Seat booked successfully" };
    }
}

export default {
    async fetch(request, env) {
        const url = new URL(request.url);
        const eventId = url.searchParams.get("event") ?? "default";

// Route to a Durable Object by event ID
        // All bookings for the same event go to the same instance
        const id = env.BOOKING.idFromName(eventId);
        const booking = env.BOOKING.get(id);

const { seatId, userId } = await request.json();
        const result = await booking.bookSeat(seatId, userId);

return Response.json(result, {
            status: result.success ? 200 : 409,
        });
    },
};

index.tsts

import { DurableObject } from "cloudflare:workers";

export interface Env {
    BOOKING: DurableObjectNamespace<SeatBooking>;
}

// ✅ Good use of Durable Objects: Seat booking requires coordination
// All booking requests for a venue must be serialized to prevent double-booking
export class SeatBooking extends DurableObject<Env> {
async bookSeat(
seatId: string,
userId: string
): Promise<{ success: boolean; message: string }> {
// Check if seat is already booked
const existing = this.ctx.storage.sql
.exec<{ user_id: string }>(
"SELECT user_id FROM bookings WHERE seat_id = ?",
seatId
)
.toArray();

if (existing.length > 0) {
            return { success: false, message: "Seat already booked" };
        }

// Book the seat - this is safe because Durable Objects are single-threaded
        this.ctx.storage.sql.exec(
            "INSERT INTO bookings (seat_id, user_id, booked_at) VALUES (?, ?, ?)",
            seatId,
            userId,
            Date.now()
        );

return { success: true, message: "Seat booked successfully" };
    }
}

export default {
    async fetch(request: Request, env: Env): Promise<Response> {
        const url = new URL(request.url);
        const eventId = url.searchParams.get("event") ?? "default";

// Route to a Durable Object by event ID
        // All bookings for the same event go to the same instance
        const id = env.BOOKING.idFromName(eventId);
        const booking = env.BOOKING.get(id);

const { seatId, userId } = await request.json<{
            seatId: string;
            userId: string;
        }>();
        const result = await booking.bookSeat(seatId, userId);

return Response.json(result, {
            status: result.success ? 200 : 409,
        });
    },
};

A common pattern is to use Workers as the stateless entry point that routes requests to Durable Objects when coordination is needed. The Worker handles authentication, validation, and response formatting, while the Durable Object handles the stateful logic.

Design and sharding

Model your Durable Objects around your "atom" of coordination

The most important design decision is choosing what each Durable Object represents. Create one Durable Object per logical unit that needs coordination: a chat room, a game session, a document, a user's data, or a tenant's workspace.

This is the key insight that makes Durable Objects powerful. Instead of a shared database with locks, each "atom" of your application gets its own single-threaded execution environment with private storage.

index.jsjs

import { DurableObject } from "cloudflare:workers";

// Each chat room is its own Durable Object instance
export class ChatRoom extends DurableObject {
    async sendMessage(userId, message) {
        // All messages to this room are processed sequentially by this single instance.
        // No race conditions, no distributed locks needed.
        this.ctx.storage.sql.exec(
            "INSERT INTO messages (user_id, content, created_at) VALUES (?, ?, ?)",
            userId,
            message,
            Date.now(),
        );
    }
}

export default {
    async fetch(request, env) {
        const url = new URL(request.url);
        const roomId = url.searchParams.get("room") ?? "lobby";

// Each room ID maps to exactly one Durable Object instance globally
        const id = env.CHAT_ROOM.idFromName(roomId);
        const stub = env.CHAT_ROOM.get(id);

await stub.sendMessage("user-123", "Hello, room!");
        return new Response("Message sent");
    },
};

index.tsts

import { DurableObject } from "cloudflare:workers";

export interface Env {
    CHAT_ROOM: DurableObjectNamespace<ChatRoom>;
}

// Each chat room is its own Durable Object instance
export class ChatRoom extends DurableObject<Env> {
    async sendMessage(userId: string, message: string) {
        // All messages to this room are processed sequentially by this single instance.
        // No race conditions, no distributed locks needed.
        this.ctx.storage.sql.exec(
            "INSERT INTO messages (user_id, content, created_at) VALUES (?, ?, ?)",
            userId,
            message,
            Date.now()
        );
    }
}

export default {
    async fetch(request: Request, env: Env): Promise<Response> {
        const url = new URL(request.url);
        const roomId = url.searchParams.get("room") ?? "lobby";

// Each room ID maps to exactly one Durable Object instance globally
        const id = env.CHAT_ROOM.idFromName(roomId);
        const stub = env.CHAT_ROOM.get(id);

await stub.sendMessage("user-123", "Hello, room!");
        return new Response("Message sent");
    },
};

Note

If you have global application or user configuration that you need to access frequently (on every request), consider using Workers KV instead.

Do not create a single "global" Durable Object that handles all requests:

index.jsjs

import { DurableObject } from "cloudflare:workers";

// 🔴 Bad: A single Durable Object handling ALL chat rooms
export class ChatRoom extends DurableObject {
    async sendMessage(roomId, userId, message) {
        // All messages for ALL rooms go through this single instance.
        // This becomes a bottleneck as traffic grows.
        this.ctx.storage.sql.exec(
            "INSERT INTO messages (room_id, user_id, content) VALUES (?, ?, ?)",
            roomId,
            userId,
            message,
        );
    }
}

export default {
    async fetch(request, env) {
        // 🔴 Bad: Always using the same ID means one global instance
        const id = env.CHAT_ROOM.idFromName("global");
        const stub = env.CHAT_ROOM.get(id);

await stub.sendMessage("room-123", "user-456", "Hello!");
        return new Response("Sent");
    },
};

index.tsts

import { DurableObject } from "cloudflare:workers";

export interface Env {
    CHAT_ROOM: DurableObjectNamespace<ChatRoom>;
}

// 🔴 Bad: A single Durable Object handling ALL chat rooms
export class ChatRoom extends DurableObject<Env> {
async sendMessage(roomId: string, userId: string, message: string) {
// All messages for ALL rooms go through this single instance.
// This becomes a bottleneck as traffic grows.
this.ctx.storage.sql.exec(
"INSERT INTO messages (room_id, user_id, content) VALUES (?, ?, ?)",
roomId,
userId,
message
);
}
}

export default {
    async fetch(request: Request, env: Env): Promise<Response> {
        // 🔴 Bad: Always using the same ID means one global instance
        const id = env.CHAT_ROOM.idFromName("global");
        const stub = env.CHAT_ROOM.get(id);

await stub.sendMessage("room-123", "user-456", "Hello!");
        return new Response("Sent");
    },
};

Message throughput limits

A single Durable Object can handle approximately 500-1,000 requests per second for simple operations. This limit varies based on the work performed per request:

Operation type	Throughput
Simple pass-through (minimal parsing)	\~1,000 req/sec
Moderate processing (JSON parsing, validation)	\~500-750 req/sec
Complex operations (transformation, storage writes)	\~200-500 req/sec

When modeling your "atom," factor in the expected request rate. If your use case exceeds these limits, shard your workload across multiple Durable Objects.

For example, consider a real-time game with 50,000 concurrent players sending 10 updates per second. This generates 500,000 requests per second total. You would need 500-1,000 game session Durable Objects—not one global coordinator.

Calculate your sharding requirements:

Required DOs = (Total requests/second) / (Requests per DO capacity)

Use deterministic IDs for predictable routing

Use getByName() with meaningful, deterministic strings for consistent routing. The same input always produces the same Durable Object ID, ensuring requests for the same logical entity always reach the same instance.

index.jsjs

import { DurableObject } from "cloudflare:workers";

export class GameSession extends DurableObject {
    async join(playerId) {
        // Game logic here
    }
}

export default {
    async fetch(request, env) {
        const url = new URL(request.url);
        const gameId = url.searchParams.get("game");

if (!gameId) {
            return new Response("Missing game ID", { status: 400 });
        }

// ✅ Good: Deterministic ID from a meaningful string
        // All requests for "game-abc123" go to the same Durable Object
        const stub = env.GAME_SESSION.getByName(gameId);

await stub.join("player-xyz");
        return new Response("Joined game");
    },
};

index.tsts

import { DurableObject } from "cloudflare:workers";

export interface Env {
    GAME_SESSION: DurableObjectNamespace<GameSession>;
}

export class GameSession extends DurableObject<Env> {
    async join(playerId: string) {
        // Game logic here
    }
}

export default {
    async fetch(request: Request, env: Env): Promise<Response> {
        const url = new URL(request.url);
        const gameId = url.searchParams.get("game");

if (!gameId) {
            return new Response("Missing game ID", { status: 400 });
        }

// ✅ Good: Deterministic ID from a meaningful string
        // All requests for "game-abc123" go to the same Durable Object
        const stub = env.GAME_SESSION.getByName(gameId);

await stub.join("player-xyz");
        return new Response("Joined game");
    },
};

Creating a stub does not instantiate or wake up the Durable Object. The Durable Object is only activated when you call a method on the stub.

Use newUniqueId() only when you need a new, random instance and will store the mapping externally:

index.jsjs

import { DurableObject } from "cloudflare:workers";

export class GameSession extends DurableObject {
    async join(playerId) {
        // Game logic here
    }
}

export default {
    async fetch(request, env) {
        // newUniqueId() creates a random ID - useful when creating new instances
        // You must store this ID somewhere (e.g., D1) to find it again later
        const id = env.GAME_SESSION.newUniqueId();
        const stub = env.GAME_SESSION.get(id);

// Store the mapping: gameCode -> id.toString()
        // await env.DB.prepare("INSERT INTO games (code, do_id) VALUES (?, ?)").bind(gameCode, id.toString()).run();

return Response.json({ gameId: id.toString() });
    },
};

index.tsts

import { DurableObject } from "cloudflare:workers";

export interface Env {
    GAME_SESSION: DurableObjectNamespace<GameSession>;
}

export class GameSession extends DurableObject<Env> {
    async join(playerId: string) {
        // Game logic here
    }
}

export default {
    async fetch(request: Request, env: Env): Promise<Response> {
        // newUniqueId() creates a random ID - useful when creating new instances
        // You must store this ID somewhere (e.g., D1) to find it again later
        const id = env.GAME_SESSION.newUniqueId();
        const stub = env.GAME_SESSION.get(id);

// Store the mapping: gameCode -> id.toString()
        // await env.DB.prepare("INSERT INTO games (code, do_id) VALUES (?, ?)").bind(gameCode, id.toString()).run();

return Response.json({ gameId: id.toString() });
    },
};

Do not put all your data in a single Durable Object. When you have hierarchical data (workspaces containing projects, game servers managing matches), create separate child Durable Objects for each entity. The parent coordinates and tracks children, while children handle their own state independently.

This enables parallelism: operations on different children can happen concurrently, while each child maintains its own single-threaded consistency (read more about this pattern).

index.jsjs

import { DurableObject } from "cloudflare:workers";

// Parent: Coordinates matches, but doesn't store match data
export class GameServer extends DurableObject {
    async createMatch(matchName) {
        const matchId = crypto.randomUUID();

// Store reference to the child in parent's database
        this.ctx.storage.sql.exec(
            "INSERT INTO matches (id, name, created_at) VALUES (?, ?, ?)",
            matchId,
            matchName,
            Date.now(),
        );

// Initialize the child Durable Object
        const childId = this.env.GAME_MATCH.idFromName(matchId);
        const childStub = this.env.GAME_MATCH.get(childId);
        await childStub.init(matchId, matchName);

return matchId;
    }

async listMatches() {
        // Parent knows about all matches without waking up each child
        const cursor = this.ctx.storage.sql.exec(
            "SELECT id, name FROM matches ORDER BY created_at DESC",
        );
        return cursor.toArray();
    }
}

// Child: Handles its own game state independently
export class GameMatch extends DurableObject {
    async init(matchId, matchName) {
        await this.ctx.storage.put("matchId", matchId);
        await this.ctx.storage.put("matchName", matchName);
        this.ctx.storage.sql.exec(`
            CREATE TABLE IF NOT EXISTS players (
                id TEXT PRIMARY KEY,
                name TEXT NOT NULL,
                score INTEGER DEFAULT 0
            )
        `);
    }

async addPlayer(playerId, playerName) {
        this.ctx.storage.sql.exec(
            "INSERT INTO players (id, name, score) VALUES (?, ?, 0)",
            playerId,
            playerName,
        );
    }

async updateScore(playerId, score) {
        this.ctx.storage.sql.exec(
            "UPDATE players SET score = ? WHERE id = ?",
            score,
            playerId,
        );
    }
}

index.tsts

```ts import { DurableObject } from "cloudflare:workers";

export interface Env { GAME_SERVER: DurableObjectNamespace<GameServer>; GAME_MATCH: DurableObjectNamespace<GameMatch>; }

// Parent: Coordinates matches, but doesn't store match data export class GameServer extends DurableObject<Env> { async createMatch(matchName: string): Promise<string> { const matchId = crypto.randomUUID();

// Store reference to the child in parent's database this.ctx.storage.sql.exec( "INSERT INTO matches (id, name, created_at) VALUES (?, ?, ?)", matchId, matchName, Date.now() );

Rules of Durable Objects

Rules of Durable Objects

When to use Durable Objects

Use Durable Objects for stateful coordination, not stateless request handling

Design and sharding

Model your Durable Objects around your "atom" of coordination

Message throughput limits

Use deterministic IDs for predictable routing

Use parent-child relationships for related entities