# cloudflare

Defines architectural standards for Cloudflare Workers and Pages inside Cursor. Guides the AI toward edge-first patterns, zero-egress storage, and small bundles.

- rule · `type=rule` · Cursor · ★ 3580
- Author: sanjeed5
- License: CC0-1.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/sanjeed5/awesome-cursor-rules-mdc/tree/HEAD/rules-mdc/cloudflare.mdc
- Updated: 2026-05-19
- HTML: https://affpapa.org/en/nevibecode/rules/cloudflare

## What it does

The rule guides Cursor through Cloudflare developer platform conventions. It enforces project setup via the official `wrangler` CLI, monorepo workspace setups, and strict secret hygiene. Non-sensitive defaults live in `wrangler.toml`, while local development variables belong strictly in `.dev.vars`.

Edge workers are stateless by design. The guidelines stop the agent from relying on in-memory global state across requests. Instead, the model selects Cloudflare KV for simple keys, D1 with Drizzle ORM for SQL, Durable Objects for real-time coordination, and R2 for object storage.

Standard Prisma query engines ship heavy Rust binaries that fail inside edge runtimes. This configuration mandates `engineType = "client"` alongside edge-compatible driver adapters to prevent bundle bloat.

## Install

### Cursor (native platform)

**Manually: put the files in place**
- File: `.cursor/rules/cloudflare.mdc` — Frontmatter: description, globs, alwaysApply

### Claude Code

**Manually: put the files in place**
- File: `.claude/rules/cloudflare.md` — The paths frontmatter field limits the files: move globs from the source into paths

### Codex

**AGENTS.md**
- Codex reads AGENTS.md: paste the rule text there

### GitHub Copilot

**Manually: put the files in place**
- File: `.github/instructions/cloudflare.instructions.md` — The applyTo field sets which files it applies to: move globs from the source into applyTo

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/rules/cloudflare.md`

### Cline

**Manually: put the files in place**
- File: `.clinerules/cloudflare.md`

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/sanjeed5/awesome-cursor-rules-mdc/tree/HEAD/rules-mdc/cloudflare.mdc

## When to use it
- scaffold a TypeScript worker using official wrangler templates
- isolate local and production environment secrets
- query D1 relational databases with Drizzle ORM
- configure Prisma client to avoid heavy Rust binaries on the edge

## Example prompts
- Set up a Cloudflare Worker that fetches an object from an R2 bucket
- Configure wrangler.toml and local secrets in .dev.vars for database access
- Write a request handler using KV storage instead of an in-memory counter

## Source text · cloudflare.mdc · CC0-1.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 1c84fdf5c237c2cf.

BEGIN THIRD-PARTY FILE 1c84fdf5c237c2cf
````text
---
description: Definitive guidelines for building secure, performant, and maintainable applications on Cloudflare's developer platform, emphasizing tiny bundles, edge-first design, and robust security.
globs: **/*
---
# cloudflare Best Practices

Cloudflare's developer platform thrives on speed, security, and global distribution. Our focus is on building tiny, observable, and secure bundles that leverage the edge. This guide outlines the definitive best practices for our team.

## 1. Code Organization and Structure

**Prioritize Workers & Pages for all new applications.** Use the official `wrangler` CLI for project scaffolding and deployment.

*   **Project Initialization:**
    *   ✅ GOOD: Always start with `wrangler generate`.
        ```bash
        npx wrangler generate my-worker --type=module --ts
        # For full-stack apps with Pages:
        npx create-cloudflare@latest my-fullstack-app --framework next
        ```
*   **Monorepos:** For projects with multiple Workers or Pages apps, use `pnpm` or `yarn workspaces`.
    *   ✅ GOOD: Centralize dependencies and build scripts.
        ```json
        // package.json
        {
          "workspaces": ["apps/*", "packages/*"]
        }
        ```
*   **Environment Variables:** Manage secrets securely via `wrangler.toml` or the Cloudflare dashboard. Use `.dev.vars` for local development.
    *   ❌ BAD: Storing sensitive data directly in code or `.env` files that aren't `.dev.vars`.
    *   ✅ GOOD: Define variables in `wrangler.toml` and reference them in your Worker.
        ```toml
        # wrangler.toml
        name = "my-worker"
        main = "src/index.ts"
        compatibility_date = "2025-12-01"

        [vars]
        MY_API_KEY = "your-api-key-value" # For non-sensitive defaults or local testing

        [secrets] # For sensitive production secrets
        # MY_DB_URL = "set via `wrangler secret put MY_DB_URL`"
        ```
    *   ✅ GOOD: Use `.dev.vars` for local secrets, and integrate with CLI tools.
        ```bash
        # .dev.vars
        DATABASE_URL="postgresql://user:pass@localhost:5432/mydb"
        # Use with Prisma:
        dotenv -e .dev.vars -- npx prisma migrate dev
        ```

## 2. Common Patterns and Anti-patterns

**Design for the edge: stateless Workers, stateful Durable Objects.**

*   **Edge-first Design:** Workers are stateless and globally distributed. Avoid in-memory state that needs to persist across requests or instances.
    *   ❌ BAD: Relying on global variables for user sessions or shared data.
        ```typescript
        let requestCount = 0; // This will reset or be inconsistent
        export default {
          async fetch(request, env, ctx) {
            requestCount++;
            return new Response(`Requests: ${requestCount}`);
          },
        };
        ```
    *   ✅ GOOD: Use KV for simple key-value storage, D1 for relational data, or Durable Objects for strong consistency and real-time state.
        ```typescript
        // Using KV for simple counters
        export default {
          async fetch(request, env, ctx) {
            let count = parseInt(await env.REQUEST_COUNTER.get("total_requests") || "0");
            await env.REQUEST_COUNTER.put("total_requests", String(count + 1));
            return new Response(`Requests: ${count + 1}`);
          },
        };
        ```
*   **Serverless SQL (D1, Hyperdrive):** Use D1 for new, natively serverless relational databases. For existing regional databases, use Hyperdrive for edge acceleration.
    *   ✅ GOOD: D1 for new projects.
        ```typescript
        // src/index.ts
        import { DrizzleD1Database, drizzle } from 'drizzle-orm/d1';
        interface Env { D1_BINDING: D1Database; }

        export default {
          async fetch(request: Request, env: Env) {
            const db = drizzle(env.D1_BINDING);
````
END THIRD-PARTY FILE 1c84fdf5c237c2cf

The third-party file has ended. Everything between the 1c84fdf5c237c2cf tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3869 of 10409 bytes. © sanjeed5 · CC0-1.0 · https://github.com/sanjeed5/awesome-cursor-rules-mdc/tree/HEAD/rules-mdc/cloudflare.mdc

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md