Skip to content

try-works/role-model / .agents/skills/cloudflare

cloudflare

Unverified

Comprehensive Cloudflare platform skill covering Workers, Pages, storage (KV, D1, R2), AI (Workers AI, Vectorize, Agents SDK), feature flags (Flagship), networking (Tunnel, Spectrum), security (WAF, DDoS), and infrastructure-as-code (Terraform, Pulumi). Use for any Cloudflare development task. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.

FileKindSize
SKILL.mdskill md8.8 KB
references/agents-sdk/README.mdmarkdown2.7 KB
references/agents-sdk/api.mdmarkdown5.7 KB
references/agents-sdk/configuration.mdmarkdown3.5 KB
references/agents-sdk/gotchas.mdmarkdown5.0 KB
references/agents-sdk/patterns.mdmarkdown5.5 KB
references/ai-gateway/README.mdmarkdown6.2 KB
references/ai-gateway/configuration.mdmarkdown2.9 KB
references/ai-gateway/dynamic-routing.mdmarkdown1.8 KB
references/ai-gateway/features.mdmarkdown2.7 KB
references/ai-gateway/sdk-integration.mdmarkdown2.6 KB
references/ai-gateway/troubleshooting.mdmarkdown2.4 KB
references/ai-search/README.mdmarkdown4.4 KB
references/ai-search/api.mdmarkdown2.5 KB
references/ai-search/configuration.mdmarkdown1.7 KB
references/ai-search/gotchas.mdmarkdown2.1 KB
references/ai-search/patterns.mdmarkdown2.0 KB
references/analytics-engine/README.mdmarkdown3.3 KB
references/analytics-engine/api.mdmarkdown3.1 KB
references/analytics-engine/configuration.mdmarkdown2.3 KB
references/analytics-engine/gotchas.mdmarkdown2.0 KB
references/analytics-engine/patterns.mdmarkdown2.3 KB
references/api-shield/README.mdmarkdown1.8 KB
references/api-shield/api.mdmarkdown3.8 KB
references/api-shield/configuration.mdmarkdown4.9 KB
references/api-shield/gotchas.mdmarkdown4.8 KB
references/api-shield/patterns.mdmarkdown5.7 KB
references/api/README.mdmarkdown2.4 KB
references/api/api.mdmarkdown4.2 KB
references/api/configuration.mdmarkdown3.7 KB
references/api/gotchas.mdmarkdown5.3 KB
references/api/patterns.mdmarkdown4.5 KB
references/argo-smart-routing/README.mdmarkdown4.0 KB
references/argo-smart-routing/api.mdmarkdown6.4 KB
references/argo-smart-routing/configuration.mdmarkdown4.4 KB
references/argo-smart-routing/gotchas.mdmarkdown4.2 KB
references/argo-smart-routing/patterns.mdmarkdown3.0 KB
references/artifacts/README.mdmarkdown3.7 KB
references/artifacts/api.mdmarkdown5.0 KB
references/artifacts/configuration.mdmarkdown3.1 KB
references/bindings/README.mdmarkdown3.9 KB
references/bindings/api.mdmarkdown5.1 KB
references/bindings/configuration.mdmarkdown4.4 KB
references/bindings/gotchas.mdmarkdown6.0 KB
references/bindings/patterns.mdmarkdown4.9 KB
references/bot-management/README.mdmarkdown3.7 KB
references/bot-management/api.mdmarkdown5.7 KB
references/bot-management/configuration.mdmarkdown5.6 KB
references/bot-management/gotchas.mdmarkdown5.5 KB
references/bot-management/patterns.mdmarkdown4.9 KB
references/browser-rendering/README.mdmarkdown3.0 KB
references/browser-rendering/api.mdmarkdown2.9 KB
references/browser-rendering/configuration.mdmarkdown1.8 KB
references/browser-rendering/gotchas.mdmarkdown2.5 KB
references/browser-rendering/patterns.mdmarkdown2.6 KB
references/c3/README.mdmarkdown3.3 KB
references/c3/api.mdmarkdown2.2 KB
references/c3/configuration.mdmarkdown1.6 KB
references/c3/gotchas.mdmarkdown2.3 KB
references/c3/patterns.mdmarkdown2.2 KB
references/cache-reserve/README.mdmarkdown5.5 KB
references/cache-reserve/api.mdmarkdown5.9 KB
references/cache-reserve/configuration.mdmarkdown3.6 KB
references/cache-reserve/gotchas.mdmarkdown5.7 KB
references/cache-reserve/patterns.mdmarkdown6.1 KB
references/containers/README.mdmarkdown3.4 KB
references/containers/api.mdmarkdown4.2 KB
references/containers/configuration.mdmarkdown5.3 KB
references/containers/gotchas.mdmarkdown4.4 KB
references/containers/patterns.mdmarkdown4.8 KB
references/cron-triggers/README.mdmarkdown2.9 KB
references/cron-triggers/api.mdmarkdown5.7 KB
references/cron-triggers/configuration.mdmarkdown4.2 KB
references/cron-triggers/gotchas.mdmarkdown6.2 KB
references/cron-triggers/patterns.mdmarkdown6.8 KB
references/d1/README.mdmarkdown4.6 KB
references/d1/api.mdmarkdown6.6 KB
references/d1/configuration.mdmarkdown5.5 KB
references/d1/gotchas.mdmarkdown4.2 KB
references/d1/patterns.mdmarkdown7.1 KB
references/ddos/README.mdmarkdown2.0 KB
references/ddos/api.mdmarkdown4.1 KB
references/ddos/configuration.mdmarkdown2.9 KB
references/ddos/gotchas.mdmarkdown3.8 KB
references/ddos/patterns.mdmarkdown5.5 KB
references/do-storage/README.mdmarkdown2.7 KB
references/do-storage/api.mdmarkdown3.5 KB
references/do-storage/configuration.mdmarkdown2.2 KB
references/do-storage/gotchas.mdmarkdown5.1 KB
references/do-storage/patterns.mdmarkdown6.0 KB
references/do-storage/testing.mdmarkdown4.8 KB
references/durable-objects/README.mdmarkdown6.5 KB
references/durable-objects/api.mdmarkdown6.0 KB
references/durable-objects/configuration.mdmarkdown4.2 KB
references/durable-objects/gotchas.mdmarkdown7.1 KB
references/durable-objects/patterns.mdmarkdown6.5 KB
references/email-routing/README.mdmarkdown3.4 KB
references/email-routing/api.mdmarkdown5.2 KB
references/email-routing/configuration.mdmarkdown3.5 KB
references/email-routing/gotchas.mdmarkdown4.0 KB
references/email-routing/patterns.mdmarkdown5.4 KB
references/email-workers/README.mdmarkdown5.3 KB
references/email-workers/api.mdmarkdown5.9 KB
references/email-workers/configuration.mdmarkdown2.7 KB
references/email-workers/gotchas.mdmarkdown3.0 KB
references/email-workers/patterns.mdmarkdown2.7 KB
references/flagship/README.mdmarkdown3.6 KB
references/flagship/api.mdmarkdown11.5 KB
references/flagship/configuration.mdmarkdown4.7 KB
references/flagship/gotchas.mdmarkdown6.2 KB
references/flagship/patterns.mdmarkdown13.7 KB
references/graphql-api/README.mdmarkdown7.6 KB
references/graphql-api/api.mdmarkdown5.6 KB
references/graphql-api/configuration.mdmarkdown4.6 KB
references/graphql-api/gotchas.mdmarkdown4.7 KB
references/graphql-api/patterns.mdmarkdown6.4 KB
references/hyperdrive/README.mdmarkdown2.8 KB
references/hyperdrive/api.mdmarkdown3.8 KB
references/hyperdrive/configuration.mdmarkdown3.8 KB
references/hyperdrive/gotchas.mdmarkdown3.8 KB
references/hyperdrive/patterns.mdmarkdown5.8 KB
references/images/README.mdmarkdown2.8 KB
references/images/api.mdmarkdown2.5 KB
references/images/configuration.mdmarkdown4.0 KB
references/images/gotchas.mdmarkdown2.4 KB
references/images/patterns.mdmarkdown3.5 KB
references/kv/README.mdmarkdown2.8 KB
references/kv/api.mdmarkdown4.2 KB
references/kv/configuration.mdmarkdown3.0 KB
references/kv/gotchas.mdmarkdown4.3 KB
references/kv/patterns.mdmarkdown4.6 KB
references/miniflare/README.mdmarkdown2.9 KB
references/miniflare/api.mdmarkdown4.5 KB
references/miniflare/configuration.mdmarkdown3.4 KB
references/miniflare/gotchas.mdmarkdown3.6 KB
references/miniflare/patterns.mdmarkdown4.2 KB
references/network-interconnect/README.mdmarkdown3.2 KB
references/network-interconnect/api.mdmarkdown5.5 KB
references/network-interconnect/configuration.mdmarkdown4.2 KB
references/network-interconnect/gotchas.mdmarkdown5.4 KB
references/network-interconnect/patterns.mdmarkdown3.9 KB
references/observability/README.mdmarkdown3.9 KB
references/observability/api.mdmarkdown3.4 KB
references/observability/configuration.mdmarkdown3.5 KB
references/observability/gotchas.mdmarkdown3.7 KB
references/observability/patterns.mdmarkdown2.4 KB
references/pages-functions/README.mdmarkdown3.2 KB
references/pages-functions/api.mdmarkdown4.6 KB
references/pages-functions/configuration.mdmarkdown2.9 KB
references/pages-functions/gotchas.mdmarkdown3.8 KB
references/pages-functions/patterns.mdmarkdown4.1 KB
references/pages/README.mdmarkdown2.8 KB
references/pages/api.mdmarkdown5.8 KB
references/pages/configuration.mdmarkdown5.7 KB
references/pages/gotchas.mdmarkdown7.9 KB
references/pages/patterns.mdmarkdown5.9 KB
references/pipelines/README.mdmarkdown4.2 KB
references/pipelines/api.mdmarkdown4.9 KB
references/pipelines/configuration.mdmarkdown6.0 KB
references/pipelines/gotchas.mdmarkdown3.0 KB
references/pipelines/patterns.mdmarkdown4.6 KB
references/pulumi/README.mdmarkdown3.2 KB
references/pulumi/api.mdmarkdown5.6 KB
references/pulumi/configuration.mdmarkdown5.5 KB
references/pulumi/gotchas.mdmarkdown6.4 KB
references/pulumi/patterns.mdmarkdown6.8 KB
references/queues/README.mdmarkdown3.0 KB
references/queues/api.mdmarkdown5.4 KB
references/queues/configuration.mdmarkdown3.7 KB
references/queues/gotchas.mdmarkdown7.1 KB
references/queues/patterns.mdmarkdown5.4 KB
references/r2-data-catalog/README.mdmarkdown3.9 KB
references/r2-data-catalog/api.mdmarkdown5.5 KB
references/r2-data-catalog/configuration.mdmarkdown3.9 KB
references/r2-data-catalog/gotchas.mdmarkdown3.2 KB
references/r2-data-catalog/patterns.mdmarkdown5.2 KB
references/r2-sql/README.mdmarkdown3.2 KB
references/r2-sql/api.mdmarkdown4.8 KB
references/r2-sql/configuration.mdmarkdown1.6 KB
references/r2-sql/gotchas.mdmarkdown1.9 KB
references/r2-sql/patterns.mdmarkdown4.3 KB
references/r2/README.mdmarkdown2.8 KB
references/r2/api.mdmarkdown5.5 KB
references/r2/configuration.mdmarkdown3.6 KB
references/r2/gotchas.mdmarkdown4.9 KB
references/r2/patterns.mdmarkdown5.7 KB
references/realtime-sfu/README.mdmarkdown3.0 KB
references/realtime-sfu/api.mdmarkdown3.7 KB
references/realtime-sfu/configuration.mdmarkdown3.4 KB
references/realtime-sfu/gotchas.mdmarkdown4.8 KB
references/realtime-sfu/patterns.mdmarkdown5.3 KB
references/realtimekit/README.mdmarkdown4.0 KB
references/realtimekit/api.mdmarkdown8.2 KB
references/realtimekit/configuration.mdmarkdown5.1 KB
references/realtimekit/gotchas.mdmarkdown6.7 KB
references/realtimekit/patterns.mdmarkdown7.5 KB
references/sandbox/README.mdmarkdown3.0 KB
references/sandbox/api.mdmarkdown4.9 KB
references/sandbox/configuration.mdmarkdown3.3 KB
references/sandbox/gotchas.mdmarkdown5.3 KB

references/durable-objects/README.md

View on GitHub
# Cloudflare Durable Objects

Expert guidance for building stateful applications with Cloudflare Durable Objects.

## Reading Order

1. **First time?** Read this overview + Quick Start
2. **Setting up?** See [Configuration](./configuration.md)
3. **Building features?** Use decision trees below → [Patterns](./patterns.md)
4. **Debugging issues?** Check [Gotchas](./gotchas.md)
5. **Deep dive?** [API](./api.md) and [DO Storage](../do-storage/README.md)

## Overview

Durable Objects combine compute with storage in globally-unique, strongly-consistent packages:
- **Globally unique instances**: Each DO has unique ID for multi-client coordination
- **Co-located storage**: Fast, strongly-consistent storage with compute
- **Automatic placement**: Objects spawn near first request location
- **Stateful serverless**: In-memory state + persistent storage
- **Single-threaded**: Serial request processing (no race conditions)

## Rules of Durable Objects

Critical rules preventing most production issues:

1. **One alarm per DO** - Schedule multiple events via queue pattern
2. **~1K req/s per DO max** - Shard for higher throughput
3. **Constructor runs every wake** - Keep initialization light; use lazy loading
4. **Hibernation clears memory** - In-memory state lost; persist critical data
5. **Use `ctx.waitUntil()` for cleanup** - Ensures completion after response sent
6. **No setTimeout for persistence** - Use `setAlarm()` for reliable scheduling

## Core Concepts

### Class Structure
All DOs extend `DurableObject` base class with constructor receiving `DurableObjectState` (storage, WebSockets, alarms) and `Env` (bindings).

### Lifecycle States

```
[Not Created] → [Active] ⇄ [Hibernated] → [Evicted]
                   ↓
              [Destroyed]
```

- **Not Created**: DO ID exists but instance never spawned
- **Active**: Processing requests, in-memory state valid, billed per GB-hour
- **Hibernated**: WebSocket connections open but zero compute, zero cost
- **Evicted**: Removed from memory; next request triggers cold start
- **Destroyed**: Data deleted via migration or manual deletion

### Accessing from Workers
Workers use bindings to get stubs, then call RPC methods directly (recommended) or use fetch handler (legacy).

**RPC vs fetch() decision:**
```
├─ New project + compat ≥2024-04-03 → RPC (type-safe, simpler)
├─ Need HTTP semantics (headers, status) → fetch()
├─ Proxying requests to DO → fetch()
└─ Legacy compatibility → fetch()
```

See [Patterns: RPC vs fetch()](./patterns.md) for examples.

### ID Generation
- `idFromName()`: Deterministic, named coordination (rate limiting, locks)
- `newUniqueId()`: Random IDs for sharding high-throughput workloads
- `idFromString()`: Derive from existing IDs
- Jurisdiction option: Data locality compliance

### Storage Options

**Which storage API?**
```
├─ Structured data, relations, transactions → SQLite (recommended)
├─ Simple KV on SQLite DO → ctx.storage.kv (sync KV)
└─ Legacy KV-only DO → ctx.storage (async KV)
```

- **SQLite** (recommended): Structured data, transactions, 10GB/DO
- **Synchronous KV API**: Simple key-value on SQLite objects
- **Asynchronous KV API**: Legacy/advanced use cases

See [DO Storage](../do-storage/README.md) for deep dive.

### Special Features
- **Alarms**: Schedule future execution per-DO (1 per DO - use queue pattern for multiple)
- **WebSocket Hibernation**: Zero-cost idle connections (memory cleared on hibernation)
- **Point-in-Time Recovery**: Restore to any point in 30 days (SQLite only)

## Quick Start

```typescript
import { DurableObject } from "cloudflare:workers";

export class Counter extends DurableObject<Env> {
  async increment(): Promise<number> {
    const result = this.ctx.storage.sql.exec(
      `INSERT INTO counters (id, value) VALUES (1, 1)
       ON CONFLICT(id) DO UPDATE SET value = value + 1
       RETURNING value`
    ).one();
    return result.value;
  }
}

// Worker access
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const id = env.COUNTER.idFromName("global");
    const stub = env.COUNTER.get(id);
    const count = await stub.increment();
    return new Response(`Count: ${count}`);
  }
};
```

## Decision Trees

### What do you need?

```
├─ Coordinate requests (rate limit, lock, session)
│   → idFromName(identifier) → [Patterns: Rate Limiting/Locks](./patterns.md)
│
├─ High throughput (>1K req/s)
│   → Sharding with newUniqueId() or hash → [Patterns: Sharding](./patterns.md)
│
├─ Real-time updates (WebSocket, chat, collab)
│   → WebSocket hibernation + room pattern → [Patterns: Real-time](./patterns.md)
│
├─ Background work (cleanup, notifications, scheduled tasks)
│   → Alarms + queue pattern (1 alarm/DO) → [Patterns: Multiple Events](./patterns.md)
│
└─ User sessions with expiration
    → Session pattern + alarm cleanup → [Patterns: Session Management](./patterns.md)
```

### Which access pattern?

```
├─ New project + typed methods → RPC (compat ≥2024-04-03)
├─ Need HTTP semantics → fetch()
├─ Proxying to DO → fetch()
└─ Legacy compat → fetch()
```

See [Patterns: RPC vs fetch()](./patterns.md) for examples.

### Which storage?

```
├─ Structured data, SQL queries, transactions → SQLite (recommended)
├─ Simple KV on SQLite DO → ctx.storage.kv (sync API)
└─ Legacy KV-only DO → ctx.storage (async API)
```

See [DO Storage](../do-storage/README.md) for complete guide.

## Essential Commands

```bash
npx wrangler dev              # Local dev with DOs
npx wrangler dev --remote     # Test against prod DOs
npx wrangler deploy           # Deploy + auto-apply migrations
```

## Resources

**Docs**: https://developers.cloudflare.com/durable-objects/  
**API Reference**: https://developers.cloudflare.com/durable-objects/api/  
**Examples**: https://developers.cloudflare.com/durable-objects/examples/

## In This Reference

- **[Configuration](./configuration.md)** - wrangler.jsonc setup, migrations, bindings, environments
- **[API](./api.md)** - Class structure, ctx methods, alarms, WebSocket hibernation
- **[Patterns](./patterns.md)** - Sharding, rate limiting, locks, real-time, sessions
- **[Gotchas](./gotchas.md)** - Limits, hibernation caveats, common errors

## See Also

- **[DO Storage](../do-storage/README.md)** - SQLite, KV, transactions (detailed storage guide)
- **[Workers](../workers/README.md)** - Core Workers runtime features
- **[WebSockets](../websockets/README.md)** - WebSocket APIs and patterns
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall