Durable Objects

A Durable Object is a special kind of Worker that uniquely combines compute (running code) with its own private storage. For any given name there is exactly one instance, living in one place, that everyone in the world talks to.

"Stateful" means it remembers things between requests. A normal Worker forgets everything the moment it finishes — it's "stateless." A Durable Object keeps its data (in memory and in durable storage), so the next request sees what the last one left behind.

Coordinating many users in real time is one of the hardest problems in software. Normally you need databases, locks, and message brokers to stop people from overwriting each other. Durable Objects make it simple: because there's only one instance per name, it naturally becomes the single point of coordination.

Reach for Durable Objects whenever multiple people or requests need to share and agree on the same live state.

You write a Durable Object as a JavaScript/TypeScript class, register it in wrangler.jsonc with a binding and a migration, then call it from a normal Worker by looking it up by name.

1. Create a Worker project

   Start from the Hello World template, then add your Durable Object class to the code.

   bashcontent_copyCopy

   npm create cloudflare@latest -- my-do-app
   cd my-do-app

2. Register the object

   In wrangler.jsonc, add a binding (the name your Worker uses) and a migration (which tells Cloudflare this is a new SQLite-backed class).

   jsonccontent_copyCopy

   {
     "durable_objects": {
       "bindings": [
         { "name": "MY_DURABLE_OBJECT", "class_name": "MyDurableObject" }
       ]
     },
     "migrations": [
       { "tag": "v1", "new_sqlite_classes": ["MyDurableObject"] }
     ]
   }

3. Deploy

   Publish to Cloudflare's network. Each unique name you request will get its own instance automatically.

   bashcontent_copyCopy

   npx wrangler deploy

import { DurableObject } from "cloudflare:workers";

export class MyDurableObject extends DurableObject {
  // Run a query against this object's own private SQLite database
  async sayHello() {
    const row = this.ctx.storage.sql
      .exec("SELECT 'Hello, World!' AS greeting")
      .one();
    return row.greeting;
  }
}

export default {
  async fetch(request, env) {
    // getByName returns the ONE instance for this name (creating it if needed)
    const stub = env.MY_DURABLE_OBJECT.getByName("room-42");
    // Call a method on it directly via RPC
    const greeting = await stub.sayHello();
    return new Response(greeting);
  },
};

Good limits to remember

• Number of objects: unlimited per account / per class
• Storage per object: up to 10 GB of SQLite on the Paid plan
• Throughput: a soft limit of ~1,000 requests/second per object
• CPU time: 30s default, configurable up to 5 minutes
• SQLite key + value combined: up to 2 MB