Cloudflare Workers + Wrangler: runtime patterns, bindings, local dev, secrets, deploy, CI/CD, observability.
\n\n\nEcosystem facts verified as of 2026-07.
\n
Version context (verified 2026-07): Wrangler v4.x · config is wrangler.jsonc (Cloudflare's recommended format for new projects — some newer features are JSON-config-only; wrangler.toml still works and is widespread in older repos) · deploy command is wrangler deploy (the old wrangler publish is deprecated — see gotchas). Workers can now serve static assets, which is the current direction for full-stack and static sites over Pages (see Workers vs Pages).
| File | \nCovers | \n
|---|---|
| references/bindings.md | \nEvery binding (KV/D1/R2/DO/Queues/Hyperdrive/AI/Vectorize/Service/Analytics Engine) — config block, runtime API, when to reach for each, consistency model | \n
| references/workers-runtime.md | \nRuntime APIs, handlers (fetch/scheduled/queue/email/tail), CORS, caching, streaming, WebSockets, Durable Objects deep-dive, limits | \n
| references/workers-runtime-gotchas.md | \nProduction footguns: detached fetch (\"Illegal invocation\"), per-colo caches vs KV vs D1, waitUntil semantics + outbox pattern, testing cron handlers, test-workerd lagging production, Email Service account states, Smart Placement, wrangler dev host rewriting | \n
| references/deploy-and-cicd.md | \nwrangler deploy, environments, secrets, Workers Builds, GitHub Actions + OIDC/API-token, gradual deployments, rollbacks, observability | \n
| assets/wrangler.jsonc.template | \nCommented, current wrangler.jsonc covering all common bindings + assets | \n
\n\nAccess / Zero Trust auth patterns (verifying
\nCf-Access-Jwt-Assertion, AUD tags, service auth, closed origins) → auth-ops skill,references/cloudflare-access.md.
Cloudflare added static-asset hosting to Workers; a single Worker now serves a static site, a full-stack app, or an API + SPA. For new projects, default to Workers with static assets. Pages still works and isn't deprecated, but Workers has the broader, faster-moving feature set (Durable Objects, Cron Triggers, Queues, richer observability) and is where Cloudflare's investment goes.
\nNew project?\n│\n├─ Pure static site (no server logic)\n│ └─ Workers + assets binding (asset-only — requests matching files never invoke Worker code, $0 for those).\n│ Pages is also fine here; Workers keeps one platform if you later add logic.\n│\n├─ Full-stack / SPA + API / SSR framework (Next, Astro, Remix, SvelteKit, Hono)\n│ └─ Workers + assets + a Worker script. Use the framework's Cloudflare adapter (C3: `npm create cloudflare@latest`).\n│ This is the current recommended path — Pages' framework story is converging into Workers.\n│\n├─ Already on Pages and happy\n│ └─ Stay. \"What works in Pages works in Workers\" — migrate only when you need a Workers-only\n│ feature (DO, Cron, Queues, advanced observability). See the migrate-from-pages guide.\n│\n└─ Need Durable Objects / Cron Triggers / Queues / Tail Workers\n └─ Workers (these are Workers-only).\nAsset serving modes (in the assets block): asset-only (no main) serves files directly and never bills Worker invocations for matches; assets + Worker serves matching files first, falls through to your fetch handler for everything else (or set run_worker_first to invoke the Worker before asset matching). Reach assets from code via env.ASSETS.fetch(request).
Full annotated version: assets/wrangler.jsonc.template.
\n{\n \"$schema\": \"node_modules/wrangler/config-schema.json\",\n \"name\": \"my-worker\",\n \"main\": \"src/index.ts\",\n \"compatibility_date\": \"2026-06-01\", // pins the runtime version — REQUIRED, bump deliberately\n \"compatibility_flags\": [\"nodejs_compat\"], // opt-in runtime features (Node built-ins, etc.)\n\n \"observability\": { \"enabled\": true }, // turn on Workers Logs (off by default)\n\n \"assets\": { \"directory\": \"./public\", \"binding\": \"ASSETS\" },\n\n \"kv_namespaces\": [{ \"binding\": \"CACHE\", \"id\": \"<kv-id>\" }],\n \"d1_databases\": [{ \"binding\": \"DB\", \"database_name\": \"app\", \"database_id\": \"<d1-id>\" }],\n \"r2_buckets\": [{ \"binding\": \"BUCKET\", \"bucket_name\": \"uploads\" }],\n\n \"vars\": { \"ENVIRONMENT\": \"production\" }, // NON-secret config only — never put secrets here\n\n \"env\": {\n \"staging\": { \"vars\": { \"ENVIRONMENT\": \"staging\" } } // named env: deploy with --env staging\n }\n}\ncompatibility_date = yyyy-mm-dd, selects the runtime version. It's required and load-bearing: bumping it can change behaviour, so do it deliberately and test. compatibility_flags opt into upcoming/Node-compat features (e.g. nodejs_compat).vars — they land in plaintext in the deployed config. Use wrangler secret put / .dev.vars (secrets).[[kv_namespaces]], [[d1_databases]], …). New repos: prefer jsonc.Full config + runtime API for every binding: references/bindings.md.
\n| Binding | \nReach for it when… | \nConsistency / note | \n
|---|---|---|
| KV | \nRead-heavy config/cache, infrequent writes, global reads | \nEventually consistent (~60s propagation). Fast reads, slow-ish writes. Not for \"read your own write\". | \n
| D1 | \nRelational/SQL data, moderate scale, per-app database | \nSQLite at the edge. Strong within a DB; read replication is async. Use for app data with joins. | \n
| R2 | \nObject/blob storage, large files, zero egress fees | \nS3-compatible. Replaces S3 for media/backups/assets you serve. | \n
| Durable Objects | \nStrong consistency, coordination, stateful realtime (chat, presence, game rooms, rate limit counters) | \nSingle-threaded per object instance = serialized = consistent. The answer when KV's eventual consistency bites. SQLite-backed storage available. | \n
| Queues | \nAsync/background work, decoupling, batching, retries | \nProducer binding + consumer Worker. Smooths spikes; guaranteed delivery with retries + DLQ. | \n
| Hyperdrive | \nConnecting to an existing external Postgres/MySQL with pooling + edge caching | \nMakes a regional DB feel fast from Workers. Needs nodejs_compat. | \n
| Workers AI | \nRun inference (LLM, embeddings, image) on Cloudflare's GPUs | \nai binding → env.AI.run(model, ...). Pairs with Vectorize for RAG. | \n
| Vectorize | \nVector DB for embeddings / semantic search / RAG | \nvectorize binding. Store + query embeddings, often fed by Workers AI. | \n
| Service bindings | \nWorker-to-Worker RPC without a network hop | \nZero-latency internal calls; compose Workers as services. | \n
Decision shortcut: need strong consistency or coordination → Durable Objects. Relational queries → D1. Big files → R2. Cheap global cache → KV. Background work → Queues. External SQL DB → Hyperdrive.
\nexport default {\n async fetch(request, env, ctx) {\n const url = new URL(request.url);\n if (url.pathname === \"/health\") return Response.json({ ok: true });\n return new Response(\"Hello from the edge\");\n },\n};\nenv carries every binding (env.DB, env.CACHE, env.ASSETS, secrets, vars). ctx.waitUntil(promise) runs background work after the response is sent. Workers require ES module format (export default { fetch }) — the old service-worker addEventListener(\"fetch\") format is legacy. Full handler patterns (scheduled/queue/email/tail, CORS, caching, WebSockets, DO): references/workers-runtime.md.
npm create cloudflare@latest my-app # C3 scaffolder — picks framework + adapter + wrangler.jsonc\nwrangler dev # local dev server (Miniflare/workerd) on localhost:8787\nwrangler dev --remote # run on Cloudflare's edge (real bindings) instead of local sim\nwrangler types # generate TS types for env from your bindings → worker-configuration.d.ts\nSecrets (never in vars):
| Where | \nMechanism | \n
|---|---|
| Local dev | \n.dev.vars file (dotenv format, gitignored) — wrangler dev loads it as env.*. Per-env: .dev.vars.staging. | \n
| Deployed | \nwrangler secret put NAME (prompts for value, encrypts it) · wrangler secret list · wrangler secret delete NAME | \n
| CI bulk | \nwrangler secret bulk secrets.json | \n
| Newer | \nCloudflare Secrets Store bindings (account-level shared secrets) — see deploy reference | \n
Add .dev.vars* to .gitignore. vars in config = plaintext public config; secrets are encrypted and write-only.
Full detail: references/deploy-and-cicd.md.
\nwrangler deploy # build + upload + activate (NOT `wrangler publish` — deprecated)\nwrangler deploy --env staging # deploy a named environment\nwrangler versions upload # upload a new version WITHOUT making it live (gradual deploys)\nwrangler versions deploy # split traffic across versions (e.g. 10% new / 90% old)\nwrangler rollback # revert to the previous deployed version\nwrangler tail # stream live logs from the deployed Worker\ncloudflare/wrangler-action. Authenticate with a scoped API token (CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID as secrets), least-privilege (Workers Scripts:Edit). Template + workflow in the deploy reference.versions upload then versions deploy to shift a percentage of traffic; instant rollback if metrics regress.\"observability\": { \"enabled\": true } in config turns on Workers Logs (structured console.log capture in the dashboard) — off by default, opt in.wrangler tail for live request log streaming during an incident.env.AE.writeDataPoint(...)), query via GraphQL/SQL API.Runtime-level footguns that pass tests and ship — detached fetch (\"Illegal invocation\"), per-colo caches, waitUntil guarantees, cron testing, the test workerd lagging production, Email Service account states, Smart Placement, wrangler dev rewriting the request host — each with symptom/why/fix: references/workers-runtime-gotchas.md.
| Gotcha | \nDetail | \nFix | \n
|---|---|---|
wrangler publish is gone | \nRenamed to wrangler deploy (Wrangler v3+). Old tutorials/CI still say publish. | \nUse wrangler deploy. Update any publish in scripts/CI. | \n
wrangler.toml vs .jsonc | \nBoth parse, but newer features are JSON-config-only and Cloudflare recommends jsonc for new projects. | \nNew projects: wrangler.jsonc. Migrating: wrangler.toml → jsonc is a mechanical 1:1. | \n
Missing compatibility_date | \nRequired; absent or stale date silently pins old runtime behaviour. | \nSet it; bump deliberately and test — it can change semantics. | \n
| CPU time limit | \nDefault 30s CPU per invocation (was 10ms/50ms historically; raised). Wall-clock can be longer while awaiting I/O. CPU-bound loops still get killed. | \nOffload heavy compute; use Queues for long async work; check the limits page for your plan. | \n
| Script size limit | \n3 MB (free) / 10 MB (paid) gzipped. | \nTrim deps, dynamic-import large modules, avoid bundling node-only libs. | \n
| KV eventual consistency | \nA write isn't globally visible for up to ~60s; not \"read your own write\". | \nUse Durable Objects when you need strong consistency. | \n
| Node built-ins fail | \nfs, crypto, etc. aren't there by default. | \n\"compatibility_flags\": [\"nodejs_compat\"] enables a polyfill subset; check what's actually supported. | \n
Secrets in vars | \nvars ships plaintext in the deployed config. | \nwrangler secret put (deployed) / .dev.vars (local). | \n
request/response body read twice | \nStreams are single-use. | \nrequest.clone() before the first read. | \n
| Bundling surprises | \nWrangler uses esbuild; some packages assume Node/CommonJS. | \nPrefer Workers-compatible libs; set nodejs_compat; check the build output. | \n
npm install -g wrangler (or use npx wrangler / npm create cloudflare@latest to scaffold).wrangler login (OAuth) for local; API token for CI.wrangler dev → wrangler deploy.This skill encodes fast-moving facts (Wrangler major line, recommended compatibility_date, wrangler.jsonc config convention). scripts/check-cloudflare-facts.py guards them against silent drift:
# Structural (PR CI, no network): every catalogued fact's prose_token is still\n# named in this skill's prose (incl. the jsonc template), and the currency\n# note still carries a year.\npython scripts/check-cloudflare-facts.py --offline # exit 0 consistent, 10 drift\n\n# Live (freshness job, never blocks a PR): wrangler still resolves on npm and\n# its latest major matches the documented v4.x line.\npython scripts/check-cloudflare-facts.py --live # exit 10 major drift, 7 npm unreachable\nThe canonical fact set lives in assets/cloudflare-facts.json; when the Wrangler major, the recommended compatibility_date, or the config convention changes, update it to match or --offline fails CI.