Durable Objects, Workers – New Best Practices guide for Durable Objects

A new Rules of Durable Objects guide is now available, providing opinionated best practices for building effective Durable Objects applications. This guide covers design patterns, storage strategies, concurrency, and common anti-patterns to avoid.

Key guidance includes:

• Design around your “atom” of coordination — Create one Durable Object per logical unit (chat room, game session, user) instead of a global singleton that becomes a bottleneck.
• Use SQLite storage with RPC methods — SQLite-backed Durable Objects with typed RPC methods provide the best developer experience and performance.
• Understand input and output gates — Learn how Cloudflare’s runtime prevents data races by default, how write coalescing works, and when to use blockConcurrencyWhile().
• Leverage Hibernatable WebSockets — Reduce costs for real-time applications by allowing Durable Objects to sleep while maintaining WebSocket connections.

The testing documentation has also been updated with modern patterns using @cloudflare/vitest-pool-workers, including examples for testing SQLite storage, alarms, and direct instance access:

• JavaScript

  import { env, runDurableObjectAlarm } from "cloudflare:test";
  import { it, expect } from "vitest";
  
  it("can test Durable Objects with isolated storage", async () => {
    const stub = env.COUNTER.getByName("test");
  
    // Call RPC methods directly on the stub
    await stub.increment();
    expect(await stub.getCount()).toBe(1);
  
    // Trigger alarms immediately without waiting
    await runDurableObjectAlarm(stub);
  });

• TypeScript

  import { env, runDurableObjectAlarm } from "cloudflare:test";
  import { it, expect } from "vitest";
  
  it("can test Durable Objects with isolated storage", async () => {
    const stub = env.COUNTER.getByName("test");
  
    // Call RPC methods directly on the stub
    await stub.increment();
    expect(await stub.getCount()).toBe(1);
  
    // Trigger alarms immediately without waiting
    await runDurableObjectAlarm(stub);
  });

Source: Cloudflare

Latest Posts