Cloudflare-first projects

A blueprint is one shape off the shelf: a facade, its ADRs, a probe pack, elicits and a guide. This page is not another blueprint; it is a map of how the Cloudflare-line blueprints compose into a whole product, and what the shelf deliberately does not cover. Every slug named here is on the shelf today and listed on the blueprints reference; every recommendation here is either an applied fact of the shipped code (probe report, contract, capability declaration) or an operator judgement your agent proposes before it applies anything.

1. When to reach for the Cloudflare line

The Cloudflare-line shelf covers a product that wants the edge, not one that grew up in a VPC. Reach for it when: the surface is served worldwide with low latency and the reads dominate the writes, the workload is bursty and event-shaped rather than long-running, the storage fits a KV cache plus a durable relational store, and the operator does not want to run a Kubernetes cluster to serve a login page. The v1.2.0 deploy-cloudflare-workers blueprint (Workers-with-static-assets) is a signal you are in this territory: a Worker plus a directory of static assets is the SPA-on-Workers shape Cloudflare itself recommends over Pages for new projects.

Do not reach for it when: the workload is a long-running process (a persistent daemon, a real background worker doing minutes of CPU per unit, a machine-learning training loop), the data fits better in a big relational store with heavy joins than in KV plus a few Postgres tables, the customer contract requires a private network with no egress, or the operator already has a mature Hetzner or on-prem estate they want the product to live on. The round-7 tunnel is the shape that lets a Cloudflare front escape to a Hetzner backend when the shelf's Cloudflare-line pieces stop fitting.

2. The deploy foot

Two shapes ship, and the elicit picks between them.

deploy-cloudflare-workers v1.2.0 is the entry blueprint. Bare-Worker is the shape when the project serves no static assets: the assets-directory elicit is left empty and no [assets] block is written to the generated wrangler.toml. SPA-on-Workers is the shape when the project ships a build-output directory of static assets alongside the Worker: assets-directory names that directory (typically ./dist, ./build, or ./public), and run-worker-first chooses whether the Worker's fetch() handler runs before the static-assets router tries to match the URL. The shipped assets-manifest-scan probe reads the applied fixture's wrangler.toml and refuses to pass while the [assets] block is missing, run_worker_first is off, or the Pages-only pages_build_output_dir field is present.

Migrating from Cloudflare Pages? Follow Cloudflare's own walkthrough at developers.cloudflare.com/workers/static-assets/migration-guides/migrate-from-pages/, apply this blueprint at v1.2.0 with assets-directory set to what the Pages project pointed at, pick run-worker-first per the project's routing shape, and drop the Pages workflow. The Workers-with-static-assets shape covers the SPA and API surfaces the Pages workflow covered.

3. Persistence choices on Cloudflare

Three durable-store blueprints and one KV facade compose here; they conflict where they should, and they do not conflict where they should not.

persistence-data-d1 is Cloudflare's own SQL store, best for a small-to-medium relational workload that fits inside a single D1 database. It is the durable store for Workers-deployed applications behind a request-scoped Worker-side facade, with numbered forward-only migrations owned by the wrangler CLI. persistence-data-postgres v1.0.0 is the Postgres shape when D1 is too small: a facade that is the sole reader of the pg client, forward-only migrations under per-file transactions, prepared-statement discipline enforced by an AST scan, and a two-path recovery model. When the Postgres host is off the edge, the round-6 Hyperdrive adapter slot is reserved at the driver boundary so the Worker fetch of a Postgres row does not pay the full-round-trip latency. persistence-data-sqlite is the third option, useful for a locally-persisted tool that runs on a single machine.

Any two of sqlite, d1, postgres deliberately conflict on the durable-store and the migration-discipline decisions: the add refuses and shows both sides. On a Cloudflare-line project the answer is almost always D1 or Postgres, not both.

platform-cloudflare-kv v1.0.0 sits alongside the durable store. KV is not a substitute for the durable store; it is the cache and the low-write metadata surface (feature flags, session mappings, a small edge-visible configuration). The facade is the sole reader of the KV namespace binding, ships a cache-aside helper on top of put and get, and emits metadata-only lifecycle events so an audit trail exists without leaking values. Declares capabilities: ["keyValueStore"].

4. Scheduling and background work

Two shapes; they compose.

platform-cloudflare-cron-triggers v1.0.0 is the shape when the project just needs a scheduled entry point on the Worker: a scheduled() handler contract with an expression-router and a skew-tolerance discipline. The probes drive wrangler dev --test-scheduled against the shared cf-platform fixture, and the shipped events (cronFired, cronSkewed, cronStalled, cronUnmatched) let the operator watch the schedule from an audit stream without pulling values through it.

jobs-background (round 5) is the shape when the project needs the whole background-work vocabulary: named job definitions with a handler, an input schema, a retry policy and a timeout, plus a scheduler that takes cron expressions and one-shot delayed runs. The scheduler mode elicit picks how the timer fires: workerCron composes with platform-cloudflare-cron-triggers and shares its skew-tolerance discipline. The round-6 Workflows scheduler-mode slot is reserved at the ADR boundary for the projects that would rather lean on Cloudflare Workflows once that reaches a production shape.

Applying jobs-background first on a bare project still refuses at add time with the queue-required refusal; --allow-no-queue-yet is the deliberate escape hatch that records the acknowledgement.

5. Edge security

Three blueprints, each guarding a slice of the ingress path. They compose along the request path; none of the three conflict with each other.

edge-cloudflare-turnstile v1.0.0 belongs on any public form that mints a credential or a transactional event (magic-link mint, sign-up, contact form). The client widget is pinned to the Cloudflare Turnstile host only, the server-side siteverify runs against https://challenges.cloudflare.com/turnstile/v0/siteverify, and a refuse-if-token-missing guard fires when the client did not present a token. The pack ships pinned public test sitekeys (1x00000000000000000000AA always-pass, 2x00000000000000000000AB always-fail, 3x00000000000000000000FF forced-interactive) with their paired secrets so a CI run needs no real Turnstile credentials to exercise the deterministic branches.

edge-cloudflare-access v1.0.0 belongs in front of admin surfaces (/admin, an ops dashboard, a runbook viewer). It is a JWT validator that is the sole reader of the Cf-Access-Jwt-Assertion header, an Access application shape, and a real-account gated-URL probe that runs accountBound-skipped without a Cloudflare account. Declares capabilities: ["zeroTrustGate"]. application-admin-console v1.1.0 consumes the capability: when Access is applied the admin console switches its sign-in surface to the Access-gated shape (no local login form, principal read from request.auth). Absent Access, the admin console falls back to the v1.0.0 local login unchanged.

edge-cloudflare-rate-limiting v1.0.0 is the zone-level guard on top of both. The rate-limit manifest lives under cloudflare/rate-limits/*.json, the drift audit checks the applied Cloudflare account against the manifest, and one accountBound-skipped burst-and-429 probe covers the throttle behaviour end to end. Declares capabilities: ["edgeRateLimit"].

Together: Turnstile in front of a public form to keep the bots out, Access in front of the admin surface to keep the wrong humans out, rate-limiting as the zone-level guard on both to cap the noise from the ones that get through.

6. Follow-up adapters

Five minor bumps land after this round rather than in it, so a project that stays on 0.24.0 today keeps working when the adapters arrive. The Postgres-backed queue sibling (messaging-queue-postgres) is reserved for projects that would rather run everything on one database. The Hyperdrive adapter slot is reserved at the persistence-data-postgres driver boundary for projects with a Postgres host off the edge. The Cloudflare Workflows scheduler-mode slot is reserved on jobs-background for projects that want to lean on Workflows once it reaches a production shape. The deploy-cloudflare-workers shape adds a follow-up when the Cloudflare-side deploy verifier needs to prove a Turnstile widget was mounted on a public form. And edge-cloudflare-access will pick up an audit-log sink adapter as the audit-event vocabulary settles.

None of these are on the shelf today; naming them here is a promise about the direction, not a commitment to a date. rcf audit view on your own project prints the reserved slots your applied blueprints have named as it walks the chain.

7. What NOT to reach for on Cloudflare

The Cloudflare-line shelf deliberately stops short of a few surfaces the platform offers.

Containers on Cloudflare: not on the shelf. The container product is fine, but the shelf's posture is that a project that wants a container has already left the Workers execution model, so a container blueprint is a different design conversation than the Cloudflare-line one this shelf is about.

Workers AI, Vectorize, AI Gateway: not on the shelf. Held pending a rcf-lite design decision on how a blueprint declares a model-serving dependency and where an LLM-inference gate lives on the chain. When that lands, an ai-* family is the likely home.

Cloudflare Pages: superseded by Workers-with-static-assets for new projects, per Cloudflare's own recommendation. The migrate-from-Pages walkthrough is the escape path.

Long-running processes and heavy compute: the shelf routes to Hetzner via the round-7 tunnel. The tunnel is not landed yet; the design lands when the round-6 shelf has settled. If your workload is a persistent daemon, a full-fat database with heavy joins, or a training loop, park the Cloudflare-line design at the deploy foot and reach out to the operator: the shape you want is a Cloudflare front-of-house plus a Hetzner back-of-house, not a Cloudflare-only stack.