How to use Cloudflare Durable Objects in Base

Most workers are stateless. Each request gets a fresh instance, anything it remembers it has to fetch from somewhere, and two requests never share memory. Durable objects break that rule on purpose. A durable object is a single, addressable, stateful instance: one named object, one place it lives, in-memory state that survives between requests, and storage attached to it. They are how you do per-entity coordination on Cloudflare, a chat room, a game session, a counter that must never miss a tick. Base wraps a durable object so that, inside it, you have a full Base worker.

A durable object is a Base worker with an address and a memory

The thing that makes Base's durable object integration click is this: inside a durable object, Base runs a real worker. Your durable object holds a settings object, and Base creates a worker from those settings, the same BaseWorker.create(settings) shape you use for a normal worker. So everything you know about Base applies inside a durable object. You declare routes, services, and dependencies the same way. The difference is that this worker has a stable identity and a memory: it is one specific object, addressed by name, and the state it holds in memory and in its attached storage persists across the requests it handles.

That framing matters. A durable object is not a different programming model bolted onto Base. It is a Base worker that happens to be singular and stateful. You bring your worker knowledge with you.

Reaching a durable object: the provider

You do not new up a durable object yourself. You ask a provider for a handle to one. The provider is created for a namespace, the named class of durable objects you declared, and it hands you a handle to a specific instance by id. The handle is typed: the provider carries the RPC interface of the durable object, so calling into the object from the outside is a typed call, not a hand-built fetch. You ask the provider for the object you want and you call its methods as if they were local, and Base carries the call across to wherever that object lives.

This is the same RPC type-sharing that makes worker-to-worker calls feel local, pointed at a stateful single instance instead of a stateless pool.

Alarms: a durable object can wake itself

A durable object can schedule itself to wake up later by setting an alarm. When the alarm fires, the object runs again, even though no request came in. This is how a durable object does delayed or recurring work tied to its own state: expire something in ten minutes, retry in an hour, tick on a timer. In Base, the alarm flows through the same scheduled path that handles cron triggers, so an alarm wake-up is handled by the scheduled machinery you already met. The object asks to be woken; the framework wakes it; your scheduled logic runs.

When to reach for a durable object

Reach for a durable object when you need one authoritative place for a piece of state and coordinated access to it: a single source of truth per entity, a coordinator that serializes operations, a session that holds live state. Do not reach for one as a general database, because the whole point is singularity and locality, one object, one home. If your data is just rows you query, the ORM is the tool. If it is a value you read everywhere, KV is the tool. The durable object is for the cases where exactly one instance must own the state.

The mental model to keep

A durable object in Base is a stateful, single-instance Base worker with an address: it runs a real worker from its settings, holds memory and storage that survive across requests, and you reach it through a typed provider that gives you a handle by id. It can wake itself with an alarm that runs through the scheduled path. Use it when one instance must own a piece of state, not as a general store.