Choose a coordination atom

A Durable Object is a globally unique stateful compute instance with private durable storage. Think of it as a tiny server that exists once per name: it keeps its own memory, has its own little database, and processes one request at a time. Requests for the same object run through that one coordination point.

That last part is the magic. Because there’s only one of each, and it handles events serially, two requests never step on each other. No race conditions, no distributed locks.

Think of a chat room. You want exactly one place that holds the messages and the list of who’s online. A Durable Object named after the room is that one place.

The name is an architectural choice

The object name decides what gets coordinated together. The same name always reaches the same instance:

const id = env.ROOMS.idFromName('team-standup')
const room = env.ROOMS.get(id)

Every request that names team-standup meets at that one instance. A different name is a different object, with separate state and separate serialization.

So the design question is: what is the unit that needs serialized state changes? Use one object per room, booking calendar, game, or tenant that needs coordination. A rate limiter gets one object per user. A collaborative document gets one object per document.

Pick the atom too big and you build a bottleneck. One global object for an entire application becomes a latency and throughput problem, because every request in the world queues behind a single instance processing them one at a time:

// every request in the app serializes through this one instance
const id = env.APP.idFromName('global')

Pick the atom too small and there’s nothing to coordinate — two objects can’t guard one invariant. If seat 12A and seat 12B must never be double-booked on the same flight, the flight is the atom, not the seat.

Practice on a real shape

Draw the objects for a collaborative notes app and explain which requests must meet at the same instance.

A reasonable answer: one object per note, because concurrent edits to one note must serialize, while edits to different notes are independent and should scale out. The list of a user’s notes doesn’t need an object at all — that’s a query, and a plain database serves it. Coordination is expensive scarcity; spend it only where two requests genuinely fight over the same state.