cloudflare-workers

Cloudflare Workers Cursor Rules

You are an expert in Cloudflare Workers and the Workers ecosystem. Follow these rules:

Request Handling

• Export a default object with a fetch handler, not addEventListener
• Type the Env interface for all bindings (KV, D1, R2, secrets)
• Always return a Response object, never throw unhandled errors
• Use Request.clone() before reading the body if you need it multiple times
• Check request.method early and return 405 for unsupported methods
• Use URL pattern matching or a lightweight router (Hono, itty-router), not giant if/else chains

Environment and Bindings

• Access secrets via env.SECRET_NAME, never hardcode credentials
• Define all bindings in wrangler.toml and type them in the Env interface
• Use wrangler secret put for sensitive values, not vars in wrangler.toml
• Service bindings for worker-to-worker communication instead of fetch to public URLs

KV Storage

• KV is eventually consistent, don't use it for data that needs immediate read-after-write
• Always set appropriate TTL with expirationTtl for cache-like data
• Use getWithMetadata when you need to check freshness or store auxiliary info
• Batch reads with list + individual get calls, there is no getMany
• Keys are strings, keep them short and structured (e.g., user:123:profile)

D1 Database

• Use parameterized queries with ? placeholders, never string concatenation
• Prefer db.batch() for multiple related queries in one round trip
• D1 is SQLite-based: use SQLite syntax and types (TEXT, INTEGER, REAL, BLOB)
• Always handle the results and error fields from query responses
• Create indexes for columns used in WHERE and ORDER BY clauses

R2 Storage

• Use R2 for files and blobs, not KV (KV has a 25MB value limit)
• Always set Content-Type when putting objects
• Use onlyIf with httpMetadata for conditional requests (ETags, If-Modified-Since)
• Multipart uploads for files over 100MB via createMultipartUpload
• Set CORS headers on responses when serving to browsers