| name | cloudflare-core |
| description | Shared reference for the Cloudflare cluster: the edge-compute + binding model every Worker turns on, wrangler.jsonc conventions, compatibility_date, the storage-primitive decision matrix (KV vs R2 vs D1 vs Durable Objects), secrets, and the auth-token gotcha. USE WHEN adding a binding, choosing a storage primitive, writing wrangler config, or debugging a Cloudflare deploy — the interlocking rules every Cloudflare spoke shares. |
| cluster | cloudflare |
| version | 1.0.0 |
Cloudflare Core
Shared model for the cloudflare cluster. The compute, storage, and deploy spokes all depend on
these interlocking concepts — keep them consistent here so no spoke contradicts another.
1. The compute + binding model (Cloudflare's defining shape)
Everything you ship is compute at the edge that reaches the rest of the platform only through
bindings. There is no ambient global state and no import of a database client — a resource exists
to your code only if it is declared as a binding:
Request ──> Worker / Pages Function ──binding──> KV · R2 · D1 · Durable Object · Queue · AI · send_email · Service
(declared in wrangler.jsonc, injected on env)
- Worker — the unit of compute; a
fetch/scheduled/email/queue handler running on every edge node. New code & reviews → workers-best-practices; deploys → cloudflare.
- Pages / Pages Functions — static assets + file-routed Workers. Deploy →
cloudflare.
- Binding — a named capability on the
env object, declared in wrangler.jsonc. This is the only way compute touches a primitive; adding one is a config change, not just code. CLI/config → wrangler.
- Durable Object — also reached via a binding, but it is compute + storage: a single-threaded, strongly-consistent actor per id. →
durable-objects.
Rule: declare every dependency as a binding; never hardcode secrets, account IDs, or
endpoints that a binding or secret should carry.
2. wrangler.jsonc & compatibility_date (the config contract)
- Prefer
wrangler.jsonc over wrangler.toml — newer features are JSON-only. → wrangler
compatibility_date pins the runtime's behavior; set a recent date (within ~30 days) and add compatibility_flags only as needed. Changing it can change runtime semantics — treat it as a real decision.- After any config/binding change, regenerate types:
wrangler types (keeps env typed).
wrangler dev for local, wrangler deploy to ship, wrangler tail for live logs.
3. Secrets & auth (where deploys actually break)
- Runtime secrets →
wrangler secret put NAME (never commit .env; never inline a token in code).
- The auth-token gotcha: API tokens in the environment frequently lack Pages permissions and silently override OAuth. For Pages — and often Workers — unset
CF_API_TOKEN/CLOUDFLARE_API_TOKEN so wrangler's OAuth login is used. This single trap causes most "works locally, 403 on deploy" failures. → cloudflare
- Account-scoped management with an explicit API token (KV/R2/Pages/DNS via scripts) →
cloudflare-manager.
4. Storage-primitive decision matrix (pick one per use)
| Primitive | Consistency | Best for | Avoid for | Spoke |
|---|
| KV | Eventual (~60s global) | Read-heavy cache, config, feature flags | Frequent writes, read-after-write | wrangler (bind), cloudflare-manager |
| R2 | Strong per-object | Large/binary objects, media, no egress fees | Querying, relational data | wrangler, r2-notebooklm-artifact-portal (public serving) |
| D1 | Strong (SQLite) | Relational data, joins, transactions | Massive write throughput, huge blobs | wrangler |
| Durable Object | Strong, single-writer | Per-entity state, coordination, locks, WebSockets, alarms | Bulk analytics, sharable read cache | durable-objects |
| Queues | At-least-once | Async/decoupled work, retries, batching | Synchronous request/response | agents-sdk, wrangler |
Rule of thumb: KV = read-heavy cache, R2 = objects, D1 = relational, Durable Object =
strongly-consistent per-entity state. Reach for a DO only when you need a single coordinator;
it is the most expensive default.
5. Higher-level SDKs (built on the same bindings)
- Agents SDK — stateful AI agents, durable workflows, scheduled tasks, MCP servers, chat/voice, React hooks. Sits on Durable Objects + Workers under the hood. →
agents-sdk
- Sandbox SDK — container-backed isolated execution for untrusted/arbitrary code, code interpreters, CI/CD, preview URLs (requires Docker locally; a
containers binding). → sandbox-sdk
- Email — send via the Workers
send_email binding or REST API; receive/route via Email Routing and onEmail(). → cloudflare-email-service
6. Retrieval over pre-training (a cluster-wide convention)
These APIs, flags, and config fields change fast. The spokes deliberately bias toward fetching
the current Cloudflare docs rather than trusting baked-in knowledge — do the same before relying
on a signature, binding shape, or wrangler flag. Authoritative sources: the spoke's linked
developers.cloudflare.com page, @cloudflare/workers-types, and
node_modules/wrangler/config-schema.json.
7. Shared guardrails
- Bindings, not hardcoding: every external dependency is a declared binding; secrets via
wrangler secret put.
- Pin
compatibility_date (recent) and run wrangler types after config changes.
- Right primitive for the access pattern (matrix above); a Durable Object is not a default cache.
- State every binding/config change — a new binding, scope, or secret is an infra change worth naming.
- Unset env API tokens for Pages/OAuth deploys — the token trap is the #1 deploy failure.
- Retrieve current docs before trusting an API signature; prefer
wrangler over hand-rolled API calls.
- Workers vs other edges: this cluster is Cloudflare-specific; the binding model and
compatibility_date are Cloudflare conventions, not portable to generic Node/serverless.
