durable-objects
Use when building stateful per-key actors — chat rooms, multiplayer rooms, rate limiters, long-running agents, leaderboards — that need persistent in-memory + storage state across requests
Profile →npx skills add butterbase-ai/butterbase-skills --skill durable-objects --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
# Butterbase Durable Objects Durable Objects (DOs) are **stateful per-key actors** running on Cloudflare Workers. Each instance has its own in-memory state and a built-in transactional KV store. Use one when state must survive across requests for a single room/user/agent. For stateless work, use a serverless function instead (`butterbase-skills:function-dev`). One tool: **`manage_durable_objects`**. --- ## 1. The mental model ``` Class: ChatRoom (deployed once) │ ├── instance "lobby" ─► in-memory state + state.storage + WebSockets ├── instance "general" ─► separate state, separate sockets └── instance "user-123" ─► separate again Each URL https://<app>.butterbase.dev/_do/chat-room/<instance-id> gets routed to the instance with that id. State is isolated per id. ``` A class is shared code; an **instance** is a unique key (`/lobby`, `/general`, `/user-123`). Different ids = different state. There is no shared cross-instance state. --- ## 2. Constraints (read these first) - **One TypeScript file per class.** No npm imports. Only `import { ... } from 'cloudflare:workers'` is allowed. - **Exactly one exported class.** `export class Foo { ... }` — no extra exports, no helpers re-exported
- 1. The mental model
- 2. Constraints (read these first)
- 3. The class skeleton
- 4. Deploy
- Access modes
- 5. Address an instance
- 6. Env vars
- 7. Lifecycle, listing, deletion
- 8. Patterns
- Chat room (broadcast)
- Sliding-window rate limiter
- Long-running AI agent
- Counter / leaderboard
- 9. Errors
What does the durable-objects skill do?
Use when building stateful per-key actors — chat rooms, multiplayer rooms, rate limiters, long-running agents, leaderboards — that need persistent in-memory + storage state across requests
How do I install it?
Run `npx skills add butterbase-ai/butterbase-skills --skill durable-objects --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From butterbase-ai/butterbase-skills, a repository with 532 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.