monkilabs/cloudflare-platform

Cloudflare Platform

Topic Routing

Read the matching reference before writing code for any of these topics:

| Topic | Reference | |-------|-----------| | Workers & edge functions | references/workers.md | | Storage (KV, D1, R2) | references/storage.md | | Pages & deployment | references/deployment.md |

Critical Rules

Workers

• Use Web standard Fetch API, not Node.js globals (process, Buffer, fs) — Workers run in V8 isolates
• Define all bindings (KV, D1, R2, secrets) in wrangler.toml and access them via the env parameter
• Workers have 0ms cold starts — keep dependencies minimal; free tier has a 1MB bundle limit
• Use ctx.waitUntil(promise) for non-blocking side effects (logging, analytics) that outlast the response

Storage Selection

• KV — key-value store for config, sessions, cache (eventually consistent reads)
• D1 — SQLite at the edge for relational SQL; strongly consistent
• R2 — object/file storage (S3-compatible); no egress costs
• Durable Objects — stateful coordination; use for real-time collaboration, rate limiters, and counters
• Queues — async message processing; use for background tasks

D1

• Use env.DB.prepare(sql).bind(...params).run() for all DML; always use parameterized queries
• Use env.DB.batch([...stmts]) for multiple queries in a single round trip
• D1 is SQLite — avoid MySQL/Postgres-only SQL syntax

MCP Code Mode

• The Cloudflare MCP uses Code Mode: only 2 tools are available — search and execute
• search searches the Cloudflare API spec; execute runs JavaScript against the Cloudflare API
• This approach uses ~1k tokens per operation vs ~244k for native tool exposure

Wrangler

• Use wrangler.toml (or wrangler.jsonc) for all config — npx wrangler dev for local dev
• npx wrangler deploy for production; wrangler tail for live log streaming
• Store secrets with wrangler secret put VAR_NAME — never hardcode in wrangler.toml

Security

• Access secrets via env.VAR_NAME — never hardcode credentials in Worker code
• Use Cloudflare Turnstile for CAPTCHA; configure WAF rules for API protection
• Validate all inputs at the Worker boundary — Workers are publicly accessible

Basic Worker with KV

// src/index.ts
export interface Env {
  SESSIONS: KVNamespace; // bound in wrangler.toml
  API_SECRET: string;    // secret bound in wrangler.toml
}

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    const url = new URL(request.url);

    if (url.pathname === '/session') {
      const sessionId = request.headers.get('x-session-id');
      if (!sessionId) return new Response('Missing session', { status: 400 });

      const data = await env.SESSIONS.get(sessionId, { type: 'json' });
      if (!data) return new Response('Not found', { status: 404 });

      // Non-blocking analytics — does not delay the response
      ctx.waitUntil(logAnalytics(sessionId));

      return Response.json(data);
    }

    return new Response('Not found', { status: 404 });
  },
} satisfies ExportedHandler<Env>;

Storage Decision Guide

I need to store data → What type?
├── Key-value pairs (cache, sessions, feature flags) → KV
├── Relational/SQL data → D1
├── Files, images, blobs → R2
├── Stateful coordination (counters, locks, chat) → Durable Objects
└── Async job queue → Queues

Reference Files

• references/workers.md — Worker structure, bindings, env, waitUntil, Durable Objects, Cron Triggers, Wrangler commands
• references/storage.md — KV, D1, R2 APIs; decision guide for choosing between storage types
• references/deployment.md — Pages setup, wrangler.toml, secrets, custom domains, CI/CD integration

Quick Workflow: Deploy a Cloudflare Worker

1. Create project: npm create cloudflare@latest and select "Hello World" Worker template
2. Define bindings (KV, D1, secrets) in wrangler.toml under [[kv_namespaces]] / [[d1_databases]]
3. Verify resources exist: npx wrangler kv:namespace list / npx wrangler d1 list — create any missing resources before continuing
   • If resource missing: npx wrangler kv:namespace create <NAME> or npx wrangler d1 create <DB> → copy the ID into wrangler.toml
4. Implement the fetch handler in src/index.ts — type the Env interface to match your bindings
5. Test locally: npx wrangler dev — verify the worker responds correctly at http://localhost:8787
   • If dev fails: check wrangler.toml syntax → verify binding IDs match → run npx wrangler whoami to confirm account auth
6. Deploy: npx wrangler deploy — confirm the deployment URL is returned
   • If deploy fails: check wrangler.toml bindings match created resources → verify compatibility_date is set → check account permissions
7. Monitor with wrangler tail for live logs from production