cloudflare-knowledge

name

cloudflare-knowledge

description

Cloudflare platform knowledge — Workers, Pages, R2, D1, KV, Durable Objects, AI, and Zero Trust. PROACTIVELY activate for: (1) Cloudflare Workers (handlers, bindings, wrangler), (2) Cloudflare Pages and Pages Functions, (3) R2 object storage, (4) D1 SQL database, (5) Workers KV and Durable Objects, (6) Workers AI inference (LLMs, embeddings, image gen), (7) Vectorize (vector database), (8) Queues and Email Workers, (9) Zero Trust (Access, Tunnel/cloudflared, Gateway), (10) DNS, WAF, Rate Limiting, Page Rules. Provides: wrangler.toml templates, binding patterns, R2/D1/KV usage, Workers AI examples, and Zero Trust config.

Cloudflare Knowledge Skill

Comprehensive Cloudflare platform knowledge covering all features, pricing, and best practices. Activate this skill when users need detailed information about Cloudflare's edge computing platform.

Activation Triggers

Activate this skill when users ask about:

• Cloudflare Workers development
• Wrangler CLI commands and configuration
• Storage services (R2, D1, KV, Durable Objects, Queues)
• Hyperdrive database connection pooling
• AI Workers (TTS, STT, LLM, image models)
• Zero Trust (tunnels, WARP, access policies)
• MCP server development and integration
• Workflows and durable execution
• Vectorize vector database
• Pages and static site deployment
• CI/CD with GitHub Actions or Workers Builds
• Observability (logs, traces, OpenTelemetry)
• Load balancing and health checks
• Cron triggers and scheduled tasks
• Cost optimization and pricing

---

Platform Overview

Cloudflare is a global edge computing platform with 300+ data centers providing:

• Workers: Serverless JavaScript/TypeScript/Python/WASM at the edge
• Pages: Static site and full-stack app hosting
• R2: S3-compatible object storage with zero egress fees
• D1: Serverless SQLite database
• KV: Eventually consistent key-value store
• Durable Objects: Stateful coordination with WebSocket support
• Queues: Async message processing
• Hyperdrive: Database connection pooling
• AI Workers: Inference at the edge (LLM, TTS, STT, image)
• Zero Trust: Identity-based security platform
• Vectorize: Vector database for RAG applications
• Workflows: Durable multi-step execution

---

Wrangler CLI Reference

Project Setup

# Create new project
npm create cloudflare@latest my-worker

# Initialize in existing directory
npx wrangler init

# Login
npx wrangler login
npx wrangler whoami

Development

# Local development
npx wrangler dev
npx wrangler dev --remote    # Use remote bindings
npx wrangler dev --local     # Fully local

# Test cron trigger locally
curl "http://localhost:8787/__scheduled?cron=*+*+*+*+*"

Deployment

# Deploy to production
npx wrangler deploy

# Deploy to environment
npx wrangler deploy --env staging

# List versions
npx wrangler versions list

# Rollback
npx wrangler rollback

D1 Database

# Create database
npx wrangler d1 create my-database

# Execute SQL
npx wrangler d1 execute my-database --local --file=schema.sql
npx wrangler d1 execute my-database --remote --command="SELECT * FROM users"

# Interactive shell
npx wrangler d1 execute my-database --local --command=".tables"

# Export
npx wrangler d1 export my-database --remote --output=backup.sql

R2 Buckets

# Create bucket
npx wrangler r2 bucket create my-bucket

# List buckets
npx wrangler r2 bucket list

# Upload/download
npx wrangler r2 object put my-bucket/file.txt --file=local.txt
npx wrangler r2 object get my-bucket/file.txt --file=download.txt

# Delete
npx wrangler r2 object delete my-bucket/file.txt

KV Namespaces

# Create namespace
npx wrangler kv namespace create MY_KV
npx wrangler kv namespace create MY_KV --preview  # Preview namespace

# List namespaces
npx wrangler kv namespace list

# Key operations
npx wrangler kv key put --binding MY_KV key "value"
npx wrangler kv key get --binding MY_KV key
npx wrangler kv key list --binding MY_KV
npx wrangler kv key delete --binding MY_KV key

# Bulk upload
npx wrangler kv bulk put --binding MY_KV data.json

Secrets

# Set secret
npx wrangler secret put API_KEY
# (prompts for value)

# List secrets
npx wrangler secret list

# Delete secret
npx wrangler secret delete API_KEY

Queues

# Create queue
npx wrangler queues create my-queue

# List queues
npx wrangler queues list

Hyperdrive

# Create Hyperdrive config
npx wrangler hyperdrive create my-hyperdrive --connection-string="postgres://..."

# List configs
npx wrangler hyperdrive list

# Update
npx wrangler hyperdrive update my-hyperdrive --connection-string="postgres://..."

---

Wrangler Configuration (wrangler.jsonc)

Complete Configuration Reference

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2024-01-01",
  "compatibility_flags": ["nodejs_compat"],

  // Account settings
  "account_id": "<optional-account-id>",

  // Build settings
  "minify": true,
  "node_compat": true,

  // Environment variables
  "vars": {
    "API_URL": "https://api.example.com"
  },

  // KV Namespaces
  "kv_namespaces": [
    {
      "binding": "MY_KV"
       
       
    
  

  
   
    
       
       
       
       
    
  

  
   
    
       
       
       
    
  

  
   
     
      
         
         
      
    
  
   
    
       
       
    
    
       
       
    
  

  
   
     
      
         
         
      
    
     
      
         
         
         
         
         
      
    
  

  
   
    
       
       
    
  

  
   
     
  

  
   
    
       
       
    
  

  
   
     
  

  
   
    
       
       
    
  

  
   
      
  

  
   
    
       
       
    
  

  
   
     
       
       
       
    
  

  
   
     
       
       
         
      
    
     
       
       
        
           
           
        
      
    
  

---

Storage Services Deep Dive

KV (Key-Value Store)

Characteristics:

• Eventually consistent (up to 60s propagation)
• Max value size: 25 MiB
• Max key size: 512 bytes
• Best for: Configuration, session data, caching
• Free tier: 100,000 reads/day, 1,000 writes/day

interface Env {
  MY_KV: KVNamespace;
}

// Write operations
await env.MY_KV.put("key", "string value");
await env.MY_KV.put("key", JSON.stringify(object));
await env.MY_KV.put("key", arrayBuffer);

// With TTL (seconds)
await env.MY_KV.put("session", data, { expirationTtl: 3600 });

// With absolute expiration
await env.MY_KV.put("session", data, { expiration: Math.floor(Date.now() / 1000) + 3600 });

// With metadata
await env.MY_KV.put("user:123", userData, {
  metadata: { type: "user", version: 2 }
});

// Read operations
const value = await env..();  
 json =  env..(, );  
 buffer =  env..(, );
 stream =  env..(, );


 { value, metadata } =  env..();


 list =  env..();
 filtered =  env..({ : , :  });



 env..();

R2 (Object Storage)

Characteristics:

• S3-compatible API
• Zero egress fees
• Max object size: 5 TB
• Single upload max: 5 GB (use multipart for larger)
• Best for: Media files, backups, data lakes, large files

interface Env {
  MY_BUCKET: R2Bucket;
}

// Put object
await env.MY_BUCKET.put("path/to/file.json", JSON.stringify(data), {
  httpMetadata: {
    contentType: "application/json",
    cacheControl: "max-age=3600",
  },
  customMetadata: {
    uploadedBy: "worker",
    version: "1.0",
  },
});

// Put with checksums
await env.MY_BUCKET.put("file.bin", data, {
  md5: expectedMd5,  // Validates on upload
  sha256: expectedSha256,
});

// Get object
const object = await env.MY_BUCKET.get("path/to/file.json");
if (object) {
  const text = await object.text();
  const json = await object.json();
  const buffer = await object.arrayBuffer();
  const blob = await .();
   stream = .;  

  
  .(., ., .);
  .(..);
  .(..);
}


 head =  env..();


 list =  env..();
 filtered =  env..({
  : ,
  : ,
  : ,
});


 env..();
 env..([, ]);  


 upload =  env..();
 part1 =  upload.(, chunk1);
 part2 =  upload.(, chunk2);
 upload.([part1, part2]);


 upload.();

D1 (SQLite Database)

Characteristics:

• Serverless SQLite
• Strong consistency
• Max database size: 10 GB (GA)
• Best for: Relational data, complex queries, ACID transactions

interface Env {
  DB: D1Database;
}

// Prepared statements (recommended)
const stmt = env.DB.prepare("SELECT * FROM users WHERE id = ?");
const { results } = await stmt.bind(userId).all();
const user = await stmt.bind(userId).first();
const value = await stmt.bind(userId).first("name");  // Single column

// Insert/Update
const { meta } = await env.DB.prepare(
  "INSERT INTO users (name, email) VALUES (?, ?)"
).bind(name, email).run();
console.log(meta.last_row_id, meta.changes);

// Batch operations (single transaction)
const results = await env.DB.batch([
  env.DB.prepare("INSERT INTO users (name) VALUES (?)").bind("Alice"),
  env.DB.prepare("INSERT INTO users (name) VALUES (?)").bind(),
  env..(),
]);


 env..();


 env..([
  env..().(, fromId),
  env..().(, toId),
]);

D1 Best Practices:

-- Create indexes for WHERE clause columns
CREATE INDEX idx_users_email ON users(email);

-- Use EXPLAIN QUERY PLAN to verify index usage
EXPLAIN QUERY PLAN SELECT * FROM users WHERE email = '[e-mail]';

-- Batch large migrations
DELETE FROM logs WHERE created_at < '2024-01-01' LIMIT 1000;

-- Run after schema changes
PRAGMA optimize;

Durable Objects

Characteristics:

• Single-threaded, globally unique instances
• Built-in SQLite storage
• WebSocket support with Hibernation
• Best for: Real-time coordination, chat, games, counters

// Durable Object class
export class Counter {
  state: DurableObjectState;
  value: number = 0;

  constructor(state: DurableObjectState, env: Env) {
    this.state = state;
    // Restore state from storage
    this.state.blockConcurrencyWhile(async () => {
      this.value = (await this.state.storage.get("value")) || 0;
    });
  }

  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url);

    switch (url.pathname) {
      case "/increment":
        this.value++;
        await this.state.storage.put(, .);
         .({ : . });

       :
         .({ : . });

      :
          (, { :  });
    }
  }
}


  {
   () {
     id = env..();
     stub = env..(id);
     stub.(request);
  },
};

WebSocket Hibernation:

export class ChatRoom {
  state: DurableObjectState;

  constructor(state: DurableObjectState, env: Env) {
    this.state = state;
  }

  async fetch(request: Request): Promise<Response> {
    if (request.headers.get("Upgrade") === "websocket") {
      const pair = new WebSocketPair();
      const [client, server] = Object.values(pair);

      // Use Hibernation API
      this.state.acceptWebSocket(server);

      return new Response(null, { status: 101, webSocket: client });
    }
    return new Response("Expected WebSocket", { status: 400 });
  }

  // Called when hibernated DO receives WebSocket message
  async webSocketMessage() {
    
     ( client  ..()) {
       (client !== ws && client. === .) {
        client.(message);
      }
    }
  }

   () {
    
  }

   () {
    
    ws.(, );
  }
}

Queues

Characteristics:

• Async message processing
• At-least-once delivery
• Automatic retries with dead letter queues
• Best for: Decoupling, background jobs, event processing

// Producer
interface Env {
  MY_QUEUE: Queue;
}

export default {
  async fetch(request: Request, env: Env) {
    // Send single message
    await env.MY_QUEUE.send({ type: "email", to: "[e-mail]" });

    // Send with options
    await env.MY_QUEUE.send(
      { type: "process", id: 123 },
      { contentType: "json" }
    );

    // Batch send
    await env.MY_QUEUE.sendBatch([
      { body: { id: 1 } },
      { body: { id: 2 } },
      { body: { id: 3 } },
    ]);

    return new Response("Queued");
  },
};

// Consumer
interface QueueMessage {
  type: string;
  ?: ;
  ?: ;
}

  {
   (: <>, : ): <> {
     ( message  batch.) {
       {
        .();
         (message.);
        message.();  
      }  (e) {
        .();
        message.();  
      }
    }
  },
};

---

AI Workers Reference

Available Models (2025-2026)

Text Generation:

Model	Context	Best For
@cf/meta/llama-3.3-70b-instruct-fp8-fast	128K	General, reasoning
@cf/mistral/mistral-7b-instruct-v0.2	32K	Fast, efficient
@cf/qwen/qwen2.5-72b-instruct	128K	Multilingual
@cf/deepseek/deepseek-r1-distill-llama-70b	64K	Complex reasoning

Text-to-Speech (TTS):

Model	Languages	Notes
@deepgram/aura-2-en	English	Best quality, context-aware
@deepgram/aura-1	English	Fast, good quality
@cf/myshell-ai/melotts	en, fr, es, zh, ja, ko	Multi-lingual

Speech-to-Text (STT):

Model	Languages	Notes
@cf/openai/whisper-large-v3-turbo	100+	Fast, accurate
@cf/openai/whisper	100+	Original Whisper

Image Generation:

Model	Resolution	Notes
@cf/black-forest-labs/flux-1-schnell	Up to 1024x1024	Fast
@cf/stabilityai/stable-diffusion-xl-base-1.0	Up to 1024x1024	Detailed

Vision/Captioning:

Model	Capabilities
@cf/meta/llama-3.2-11b-vision-instruct	Image understanding, captioning
@cf/llava-hf/llava-1.5-7b-hf	Visual Q&A

Embeddings:

Model	Dimensions	Notes
@cf/baai/bge-large-en-v1.5	1024	Best quality
@cf/baai/bge-small-en-v1.5	384	Faster

Usage Examples

interface Env {
  AI: Ai;
}

// Text generation
const response = await env.AI.run("@cf/meta/llama-3.3-70b-instruct-fp8-fast", {
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "What is Cloudflare?" },
  ],
  max_tokens: 512,
  temperature: 0.7,
});

// Streaming
const stream = await env.AI.run("@cf/meta/llama-3.3-70b-instruct-fp8-fast", {
  messages: [...],
  stream: true,
});
return new Response(stream, {
  headers: { "Content-Type": "text/event-stream" },
});

// Text-to-Speech
const audio = await env.AI.run("@deepgram/aura-2-en", {
  text: "Hello, this is a test.",
});
return new Response(audio, {
  headers: { "Content-Type":  },
});


 transcript =  env..(, {
  : audioArrayBuffer,
});



 image =  env..(, {
  : ,
  : ,
});
  (image, {
  : { :  },
});


 embeddings =  env..(, {
  : [, ],
});



 caption =  env..(, {
  : imageArrayBuffer,
  : ,
});

---

Hyperdrive Deep Dive

Hyperdrive accelerates database connections by maintaining connection pools close to your database.

Setup

# Create Hyperdrive config
npx wrangler hyperdrive create my-db \
  --connection-string="postgres://user:pass@host:5432/database"

# Add to wrangler.jsonc

Usage

import { Client } from "pg";

interface Env {
  MY_DB: Hyperdrive;
}

export default {
  async fetch(request: Request, env: Env) {
    // Connect using Hyperdrive connection string
    const client = new Client({
      connectionString: env.MY_DB.connectionString,
    });

    await client.connect();
    const result = await client.query("SELECT * FROM users WHERE id = $1", [1]);

    // No need to call client.end() - Hyperdrive manages pooling
    return Response.json(result.rows);
  },
};

When to Use Hyperdrive

Use Hyperdrive when:

• Connecting to remote PostgreSQL/MySQL databases
• High-latency database connections (different regions)
• Frequent identical read queries (caching)
• Many concurrent database connections needed

Don't use Hyperdrive when:

• Using D1 (already edge-native)
• Local development (use direct connection)
• Need prepared statements across requests (transaction mode limitation)
• Using Durable Objects storage

Performance Benefits

Without Hyperdrive:

Worker -> TCP handshake (1 RTT)
       -> TLS negotiation (3 RTTs)
       -> DB authentication (3 RTTs)
       -> Query (1 RTT)
Total: 8 round-trips before first query

With Hyperdrive:

Worker -> Hyperdrive pool (cached connection)
       -> Query (1 RTT to pool, reuses DB connection)
Total: 1 round-trip to query

---

Zero Trust Reference

Cloudflare Tunnel

Expose internal services securely without opening firewall ports.

Installation:

# macOS
brew install cloudflared

# Windows
winget install Cloudflare.cloudflared

# Linux
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o cloudflared
sudo chmod +x cloudflared && sudo mv cloudflared /usr/local/bin/

Setup:

# Login
cloudflared tunnel login

# Create tunnel
cloudflared tunnel create my-tunnel

# Create config file (~/.cloudflared/config.yml)
cat << EOF > ~/.cloudflared/config.yml
tunnel: <tunnel-id>
credentials-file: $HOME/.cloudflared/<tunnel-id>.json

ingress:
  - hostname: app.example.com
    service: http://localhost:3000
  - hostname: api.example.com
    service: http://localhost:8080
  - service: http_status:404
EOF

# Add DNS
cloudflared tunnel route dns my-tunnel app.example.com

# Run
cloudflared tunnel run my-tunnel

Run as Service:

# Linux
sudo cloudflared service install
sudo systemctl enable cloudflared
sudo systemctl start cloudflared

# macOS
sudo cloudflared service install
sudo launchctl load /Library/LaunchDaemons/com.cloudflare.cloudflared.plist

Access Policies

Configure in Cloudflare dashboard (Zero Trust > Access > Applications):

Application:
  name: Internal App
  type: Self-hosted
  domain: app.example.com

Policy:
  name: Allow Company
  action: Allow
  include:
    - email_domain: company.com
  require:
    - country: US

WARP Client

• Device client for Zero Trust enrollment
• Routes traffic through Cloudflare network
• Enables identity-based access policies
• Split tunneling for selective routing

---

MCP Servers Reference

Building MCP Server on Workers

import { McpServer } from "@cloudflare/mcp-server";

interface Env {
  DB: D1Database;
}

const server = new McpServer({
  name: "my-mcp-server",
  version: "1.0.0",
});

// Define tools
server.addTool({
  name: "query_database",
  description: "Query the D1 database",
  parameters: {
    type: "object",
    properties: {
      query: { type: "string", description: "SQL query to execute" },
    },
    required: ["query"],
  },
  handler: async ({ query }, { env }) => {
    const result = await env.DB.prepare(query).all();
    return {
      content: [{ type: "text", text: JSON.stringify(result.results) }],
    };
  },
});

// Define resources
server.addResource({
  uri: "db://tables",
  name: ,
  : ,
  :  ({ env }) => {
     tables =  env..(
      
    ).();
     {
      : [{ : , : .(tables.) }],
    };
  },
});

  {
   () {
     server.(request, env);
  },
};

MCP Transport Types

1. Streamable HTTP (Recommended, March 2025+)

   • Single HTTP endpoint
   • Bidirectional messaging
   • Standard for remote MCP

2. stdio (Local only)

   • Standard input/output
   • For local MCP connections

3. SSE (Deprecated)

   • Use Streamable HTTP instead

Cloudflare's Managed MCP Servers

Available at https://mcp.cloudflare.com/:

• Workers management
• R2 bucket operations
• D1 database queries
• DNS management
• Analytics access

Connect from Claude/Cursor:

{
  "mcpServers": {
    "cloudflare": {
      "url": "https://mcp.cloudflare.com/sse",
      "transport": "sse"
    }
  }
}

---

CI/CD Reference

GitHub Actions

name: Deploy Worker

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

      - name: Deploy to Cloudflare
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

Workers Builds (Native Git Integration)

1. Connect GitHub/GitLab in Cloudflare dashboard
2. Select repository and branch
3. Configure build command (optional)
4. Automatic deployment on push
5. Preview URLs for pull requests

---

Pricing Reference (2025-2026)

Workers

Plan	Price	Requests	CPU Time
Free	$0	100K/day	10ms/invocation
Paid	$5/mo	10M included	30s/invocation
Usage	+$0.30/M requests	-	$0.02/M ms

Storage

Service	Free Tier	Paid
KV	100K reads, 1K writes/day	$0.50/M reads, $5/M writes
R2	10GB storage, 10M Class A ops	$0.015/GB, $4.50/M Class A
D1	5M rows read, 100K writes/day	$0.001/M rows, $1/M writes
Durable Objects	1M requests	$0.15/M requests
Queues	1M messages	$0.40/M messages

AI Workers

• Pay per inference
• Varies by model (check dashboard for current pricing)
• Free tier includes limited inferences

---

Best Practices

Performance

1. Use edge caching: Cache API responses with caches.default
2. Minimize cold starts: Keep Workers small, use dynamic imports
3. Use Service Bindings: Zero-cost Worker-to-Worker calls
4. Batch operations: Combine KV/R2/D1 operations
5. Use Hyperdrive: For remote database connections

Security

1. Use secrets: Never hardcode credentials
2. Validate input: Sanitize all user input
3. Use HTTPS: Always use secure connections
4. Implement rate limiting: Protect against abuse
5. Use Zero Trust: For internal service access

Cost Optimization

1. Use Static Assets: Free, unlimited static file serving
2. Sample logs: Use head_sampling_rate for high-traffic Workers
3. Use KV for caching: Reduce D1/external API calls
4. Batch queue messages: Reduce per-message overhead
5. Use GPU-appropriate models: Don't overprovision AI

---

Quick Reference

Task	Command/Code
New project	npm create cloudflare@latest
Local dev	npx wrangler dev
Deploy	npx wrangler deploy
Create D1	npx wrangler d1 create name
Create KV	npx wrangler kv namespace create NAME
Create R2	npx wrangler r2 bucket create name
Set secret	npx wrangler secret put NAME
Create queue	npx wrangler queues create name
Create tunnel	cloudflared tunnel create name