{"id":10432,"date":"2026-07-20T12:20:21","date_gmt":"2026-07-20T17:20:21","guid":{"rendered":"https:\/\/master.dev\/blog\/?p=10432"},"modified":"2026-07-20T12:20:23","modified_gmt":"2026-07-20T17:20:23","slug":"durable-objects-on-cloudflare","status":"publish","type":"post","link":"https:\/\/master.dev\/blog\/durable-objects-on-cloudflare\/","title":{"rendered":"Durable Objects on Cloudflare"},"content":{"rendered":"\n

This is a post on one of Cloudflare’s coolest features: Durable Objects. We’ll introduce what they are, how they work, and walk through a reasonably realistic use case for them.<\/p>\n\n\n\n

Cloudflare Workers Review<\/h2>\n\n\n\n

I’ve written about Cloudflare Workers previously, with an introduction to them<\/a> and a post about some of the slightly unorthodox things you have to do to use a database with them<\/a>.<\/p>\n\n\n\n

We won’t rehash all of that here, but briefly, Cloudflare Workers are like AWS Lambda functions, except they have much, much lower latency. There are significant differences between those technologies, to be clear. But the high-level elevator pitch is that workers spin up extremely quickly, with virtually no “cold start” to satisfy requests against your web application. And these workers spin up as much as needed, giving you built-in horizontal scaling, no matter how spiky your traffic is at any given time.<\/p>\n\n\n\n

What’s Missing From Workers Alone?<\/h2>\n\n\n\n

State. <\/p>\n\n\n\n

Anonymous Cloudflare workers that can spin up, serve your request, and die off are fantastic for satisfying spiky, growing traffic. But they’re terrible for managing long-running state. How could they? They’re the absolute opposite of long-running, so they’re not capable of managing long-running state.<\/p>\n\n\n\n

What are Durable Objects?<\/h2>\n\n\n\n

Durable Objects<\/a> are Cloudflare’s answer to this. Durable Objects are stateful worker instances that include their own persistent storage (either SQLite or Cloudflare’s key-value storage). Durable Objects are, well, durable. They go idle when not in use, but when requests against them resume, they come back to life with access to their persistent storage.<\/p>\n\n\n\n

Cloudflare guarantees that each Durable Object instance is active in only one location at a time. While active, it can cache state in memory for fast access, with the source of truth in its persistent storage (SQLite or KV storage).<\/p>\n\n\n\n

Plus, WebSocket Support<\/h3>\n\n\n\n

We’ll get into the specifics, but Durable Objects also ship with built-in<\/em> WebSocket support. You can set up multiple socket connections, post and receive messages, and so on.<\/p>\n\n\n\n

Our Use Case: a Shopping Cart<\/h2>\n\n\n\n

Let\u2019s set up a Durable Object to hold the shopping cart for a hypothetical e-commerce site. We\u2019ll create one Durable Object instance for each user. The user’s cart contents will follow them around to any browser on any device (so long as they’re logged in).<\/p>\n\n\n\n

Sure, you could do the same thing with Postgres, but our Durable Object will come with some other nice features: anytime a user adds an item to the cart, we’ll use that web socket feature we just mentioned to broadcast to all devices that the cart has changed, and that the cart contents should refresh.<\/p>\n\n\n\n

Plus, our Durable Object will cache the cart’s contents in memory while active, avoiding what would otherwise be a round trip to the database powering your web app.<\/p>\n\n\n\n

Setting Up a Durable Object<\/h2>\n\n\n\n

As we did in the intro<\/a>, we’ll use TanStack Start<\/a> here too. The repo for everything is here<\/a> in case I don’t explain or show anything clearly.<\/p>\n\n\n\n\n

\n
\n \"TanStack\n <\/a> <\/div>\n \n
\n \n

\n TanStack Start & TanStack Query<\/a>\n <\/h3>\n \n \n
\n \"Adam\n
\n Adam Rackis<\/span>\n Spotify<\/span>\n <\/div>\n <\/div>\n \n <\/div>\n <\/div>\n\n\n\n\n

Create the Durable Object<\/h3>\n\n\n\n

A Durable Object is created from a JavaScript class with the appropriate base class.<\/p>\n\n\n

import<\/span> { DurableObject } from<\/span> \"cloudflare:workers\"<\/span>;\n\nexport<\/span> class<\/span> CartDO<\/span> extends<\/span> DurableObject<\/span> <\/span>{}<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
We’ll add methods to it in a bit.<\/p>\n\n\n\n
Custom Server Entrypoint<\/h3>\n\n\n\n
We need to ensure our Durable Object is exported with our application bundle. The recommended way of doing that is with a custom server entrypoint. We’ll create a src\/server.ts<\/code> file.<\/p>\n\n\n
import<\/span> handler from<\/span> \"@tanstack\/react-start\/server-entry\"<\/span>;\n\nexport<\/span> default<\/span> {\n  fetch: handler.fetch,\n};<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
This alone does nothing and simply recreates what TanStack Start does out of the box. The point of that is so we can export<\/em> our Durable Object from this same entrypoint. We do that with a standard old JavaScript export.<\/p>\n\n\n
import<\/span> handler from<\/span> \"@tanstack\/react-start\/server-entry\"<\/span>;\n\n\/\/ Export Durable Objects<\/span>\nexport<\/span> { CartDO } from<\/span> \".\/durable-obj\/Cart\"<\/span>;\n\nexport<\/span> default<\/span> {\n  fetch: handler.fetch,\n};<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
\"main\"<\/span>: \"@tanstack\/react-start\/server-entry\"<\/span>,<\/code><\/span>Code language:<\/span> JSON \/ JSON with Comments<\/span> (<\/span>json<\/span>)<\/span><\/small><\/pre>\n\n\n
To:<\/p>\n\n\n
\"main\"<\/span>: \"src\/server.ts\"<\/span>,<\/code><\/span>Code language:<\/span> JSON \/ JSON with Comments<\/span> (<\/span>json<\/span>)<\/span><\/small><\/pre>\n\n\n
More Wrangler Additions<\/h3>\n\n\n\n
That custom server entrypoint was a one-time change that allows us<\/em> to then start adding in Cloudflare goodies like durable objects (naturally), queues, or cron schedules. Check Cloudflares docs<\/a> for more info.<\/p>\n\n\n\n
So now we’ll add a durable_objects<\/code> section with a binding to the Durable Object we added above.<\/p>\n\n\n
  \"durable_objects\"<\/span>: {\n    \"bindings\"<\/span>: [\n      {\n        \"name\"<\/span>: \"CART_DO\"<\/span>,\n        \"class_name\"<\/span>: \"CartDO\"<\/span>,\n      },\n    ],\n  },<\/code><\/span>Code language:<\/span> JSON \/ JSON with Comments<\/span> (<\/span>json<\/span>)<\/span><\/small><\/pre>\n\n\n
Then, somewhat annoyingly, we need to add a migration for it as well.<\/p>\n\n\n
  \"migrations\"<\/span>: [\n    {\n      \"tag\"<\/span>: \"v1\"<\/span>,\n      \"new_sqlite_classes\"<\/span>: [\"CartDO\"<\/span>],\n    },\n  ],<\/code><\/span>Code language:<\/span> JSON \/ JSON with Comments<\/span> (<\/span>json<\/span>)<\/span><\/small><\/pre>\n\n\n
Building our Durable Object<\/h2>\n\n\n\n
To avoid dumping too much code at you all at once, let’s sketch out a minimal version of our Shopping Cart, just to see how everything works and fits together. Let’s create the following methods:<\/p>\n\n\n\n
And now we change the main<\/code> field in our Wrangler file (remember: Wrangler<\/a> is the CLI tool from Cloudflare for managing our Workers settings) from the default of:<\/p>\n\n\n