mizchi/cloudflare-deploy

Cloudflare Deploy

Consolidated skill for building on the Cloudflare platform. Use decision trees below to find the right product, then load detailed references.

Prerequisites

• When sandboxing blocks the deployment network calls, rerun with sandbox_permissions=require_escalated.
• The deployment might take a few minutes. Use appropriate timeout values.

Authentication (Required Before Deploy)

Verify auth before wrangler deploy, wrangler pages deploy, or npm run deploy:

npx wrangler whoami    # Shows account if authenticated

Not authenticated? → references/wrangler/auth.md

• Interactive/local: wrangler login (one-time OAuth)
• CI/CD: Set CLOUDFLARE_API_TOKEN env var

When to Read references/

This SKILL.md is an index + decision tree. Actual implementation details (wrangler.jsonc binding syntax, SDK-specific APIs, product gotchas) live under references/<product>/.

Rules of thumb:

• Picking a product? Use decision trees below, then load references/<picked-product>/
• Writing a new wrangler.jsonc? Always references/workers/configuration.md first (binding shapes are non-inheritable and easy to get wrong)
• CI/CD setup? Load references/ci/github-actions.md (GitHub Actions + OIDC + PR preview + tag deploy recipes)
• Deploy fails / unexpected error? Grep references/<product>/gotchas.md before re-running
• The minimal example below covers Workers + KV + secret — for anything beyond that, descend into references

Minimal Worker Example (copy-paste starter)

For a Hello-world Worker with one KV binding and one secret, you don't need to read references/ at all:

// wrangler.jsonc
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-04-01",
  "compatibility_flags": ["nodejs_compat"],
  "observability": { "enabled": true },
  "kv_namespaces": [
    { "binding": "CACHE", "id": "<replace-with-kv-id>" }
  ]
}

// src/index.ts
export interface Env {
  CACHE: KVNamespace;
  API_SECRET: string;
}
export default {
  async fetch(req: Request, env: Env): Promise<Response> {
    const hit = await env.CACHE.get("greeting");
    return new Response(hit ?? "hello");
  }
};

Bootstrap commands:

npx wrangler kv namespace create CACHE          # copy printed id into wrangler.jsonc
npx wrangler secret put API_SECRET              # paste value interactively
npx wrangler types                              # generate Env types (optional)
npx wrangler dev                                # local dev at localhost:8787
npx wrangler deploy                             # production deploy

Pick compatibility_date = today's date (YYYY-MM-DD). Update when upgrading wrangler.

For Pages / D1 / Durable Objects / multi-env / CI — descend into references/.

Quick Decision Trees

"I need to run code"

Need to run code?
├─ Serverless functions at the edge → workers/
├─ Full-stack web app with Git deploys → pages/
├─ Stateful coordination/real-time → durable-objects/
├─ Long-running multi-step jobs → workflows/
├─ Run containers → containers/
├─ Multi-tenant (customers deploy code) → workers-for-platforms/
├─ Scheduled tasks (cron) → cron-triggers/
├─ Lightweight edge logic (modify HTTP) → snippets/
├─ Process Worker execution events (logs/observability) → tail-workers/
└─ Optimize latency to backend infrastructure → smart-placement/

"I need to store data"

Need storage?
├─ Key-value (config, sessions, cache) → kv/
├─ Relational SQL → d1/ (SQLite) or hyperdrive/ (existing Postgres/MySQL)
├─ Object/file storage (S3-compatible) → r2/
├─ Message queue (async processing) → queues/
├─ Vector embeddings (AI/semantic search) → vectorize/
├─ Strongly-consistent per-entity state → durable-objects/ (DO storage)
├─ Secrets management → secrets-store/
├─ Streaming ETL to R2 → pipelines/
└─ Persistent cache (long-term retention) → cache-reserve/

"I need AI/ML"

Need AI?
├─ Run inference (LLMs, embeddings, images) → workers-ai/
├─ Vector database for RAG/search → vectorize/
├─ Build stateful AI agents → agents-sdk/
├─ Gateway for any AI provider (caching, routing) → ai-gateway/
└─ AI-powered search widget → ai-search/

"I need networking/connectivity"

Need networking?
├─ Expose local service to internet → tunnel/
├─ TCP/UDP proxy (non-HTTP) → spectrum/
├─ WebRTC TURN server → turn/
├─ Private network connectivity → network-interconnect/
├─ Optimize routing → argo-smart-routing/
├─ Optimize latency to backend (not user) → smart-placement/
└─ Real-time video/audio → realtimekit/ or realtime-sfu/

"I need security"

Need security?
├─ Web Application Firewall → waf/
├─ DDoS protection → ddos/
├─ Bot detection/management → bot-management/
├─ API protection → api-shield/
├─ CAPTCHA alternative → turnstile/
└─ Credential leak detection → waf/ (managed ruleset)

"I need media/content"

Need media?
├─ Image optimization/transformation → images/
├─ Video streaming/encoding → stream/
├─ Browser automation/screenshots → browser-rendering/
└─ Third-party script management → zaraz/

"I need infrastructure-as-code"

Need IaC? → pulumi/ (Pulumi), terraform/ (Terraform), or api/ (REST API)

Product Index

Compute & Runtime

| Product | Reference | |---------|-----------| | Workers | references/workers/ | | Pages | references/pages/ | | Pages Functions | references/pages-functions/ | | Durable Objects | references/durable-objects/ | | Workflows | references/workflows/ | | Containers | references/containers/ | | Workers for Platforms | references/workers-for-platforms/ | | Cron Triggers | references/cron-triggers/ | | Tail Workers | references/tail-workers/ | | Snippets | references/snippets/ | | Smart Placement | references/smart-placement/ |

Storage & Data

| Product | Reference | |---------|-----------| | KV | references/kv/ | | D1 | references/d1/ | | R2 | references/r2/ | | Queues | references/queues/ | | Hyperdrive | references/hyperdrive/ | | DO Storage | references/do-storage/ | | Secrets Store | references/secrets-store/ | | Pipelines | references/pipelines/ | | R2 Data Catalog | references/r2-data-catalog/ | | R2 SQL | references/r2-sql/ |

AI & Machine Learning

| Product | Reference | |---------|-----------| | Workers AI | references/workers-ai/ | | Vectorize | references/vectorize/ | | Agents SDK | references/agents-sdk/ | | AI Gateway | references/ai-gateway/ | | AI Search | references/ai-search/ |

Networking & Connectivity

| Product | Reference | |---------|-----------| | Tunnel | references/tunnel/ | | Spectrum | references/spectrum/ | | TURN | references/turn/ | | Network Interconnect | references/network-interconnect/ | | Argo Smart Routing | references/argo-smart-routing/ | | Workers VPC | references/workers-vpc/ |

Security

| Product | Reference | |---------|-----------| | WAF | references/waf/ | | DDoS Protection | references/ddos/ | | Bot Management | references/bot-management/ | | API Shield | references/api-shield/ | | Turnstile | references/turnstile/ |

Media & Content

| Product | Reference | |---------|-----------| | Images | references/images/ | | Stream | references/stream/ | | Browser Rendering | references/browser-rendering/ | | Zaraz | references/zaraz/ |

Real-Time Communication

| Product | Reference | |---------|-----------| | RealtimeKit | references/realtimekit/ | | Realtime SFU | references/realtime-sfu/ |

Developer Tools

| Product | Reference | |---------|-----------| | Wrangler | references/wrangler/ | | Miniflare | references/miniflare/ | | C3 | references/c3/ | | Observability | references/observability/ | | Analytics Engine | references/analytics-engine/ | | Web Analytics | references/web-analytics/ | | Sandbox | references/sandbox/ | | Workerd | references/workerd/ | | Workers Playground | references/workers-playground/ |

Infrastructure as Code

| Product | Reference | |---------|-----------| | Pulumi | references/pulumi/ | | Terraform | references/terraform/ | | API | references/api/ |

Other Services

| Product | Reference | |---------|-----------| | Email Routing | references/email-routing/ | | Email Workers | references/email-workers/ | | Static Assets | references/static-assets/ | | Bindings | references/bindings/ | | Cache Reserve | references/cache-reserve/ |

Troubleshooting

Escalated Network Access

If deployment fails due to network issues (timeouts, DNS errors, connection resets), rerun the deploy with escalated permissions (use sandbox_permissions=require_escalated). The deploy requires escalated network access when sandbox networking blocks outbound requests.

Example guidance to the user:

The deploy needs escalated network access to deploy to Cloudflare. I can rerun the command with escalated permissions—want me to proceed?