Cloudflare Hono Template Guide

A comprehensive guide to using the Cloudflare Hono template with Orchestre.

Overview

The cloudflare-hono template is optimized for edge computing with:

• Global edge deployment
• Sub-millisecond response times
• Built-in KV storage and Durable Objects
• Hono framework for modern APIs
• D1 database for SQL at the edge

Getting Started

Initialize a New Project

# Create a new Cloudflare Workers project
/orchestre:create (MCP) "my-api" using cloudflare-hono

# Specify a custom path
/orchestre:create (MCP) "my-api" using cloudflare-hono at ~/projects/edge-api

What You Get

When you initialize a Cloudflare project, Orchestre provides:

• Edge-optimized project structure with Hono
• .orchestre/prompts.json with edge-specific commands
• CLAUDE.md files for tracking decisions
• Template-aware prompts that understand Workers constraints

Building Edge Applications

1. Global API Gateway

Build a high-performance API gateway:

# Plan the architecture
/orchestre:orchestrate (MCP) "Design API gateway with rate limiting and caching"

# Implement core features
/orchestre:execute-task (MCP) "Add token bucket rate limiting with KV"
/orchestre:execute-task (MCP) "Implement intelligent edge caching"
/orchestre:execute-task (MCP) "Add request routing with middleware"

2. Real-time Collaboration

Create WebSocket-based services:

# Design real-time features
/orchestre:orchestrate (MCP) "Plan real-time collaboration with Durable Objects"

# Build the system
/orchestre:execute-task (MCP) "Create Durable Object for room state"
/orchestre:execute-task (MCP) "Implement WebSocket message broadcasting"
/orchestre:execute-task (MCP) "Add presence tracking with heartbeats"

3. Image Processing Service

On-demand image transformation:

# Plan the service
/orchestre:orchestrate (MCP) "Design image processing pipeline with R2"

# Implementation
/orchestre:execute-task (MCP) "Create image resize endpoint"
/orchestre:execute-task (MCP) "Set up R2 storage for processed images"
/orchestre:execute-task (MCP) "Add CDN caching headers"

Common Patterns

Edge Authentication

# JWT validation at edge
/add-middleware "JWT authentication middleware"

# API key management
/add-auth-system "API key validation with KV"

Data Storage

# KV for fast reads
/add-kv-namespace "User session storage"

# D1 for relational data
/add-d1-database "Set up SQLite at the edge"

# R2 for objects
/add-r2-storage "File storage bucket"

Performance Optimization

# Smart caching
/add-caching-layer "Cache with edge TTL"

# Request coalescing
/optimize-performance "Implement request deduplication"

Working with Cloudflare Workers

Using Orchestre Commands

With Orchestre v5, commands are provided as MCP prompts that understand Cloudflare Workers:

1. Core Orchestration - Universal commands:

   • /orchestre:create - Initialize new Workers projects
   • /orchestre:orchestrate - Plan edge-optimized features
   • /orchestre:execute-task - Build with Workers best practices
   • /orchestre:review - Review for edge constraints

2. Edge Context - Workers-specific understanding:

   • Commands know about Workers limitations
   • Intelligent suggestions for edge patterns
   • Automatic optimization recommendations

Development Workflow

# 1. Plan your edge feature
/orchestre:orchestrate (MCP) "Design geolocation-based routing"

# 2. Implement with edge constraints
/orchestre:execute-task (MCP) "Build the routing middleware"

# 3. Review for performance
/orchestre:review (MCP) "Check for subrequest optimization"

Best Practices

1. Design for the Edge

# Plan for minimal cold starts
/orchestre:orchestrate (MCP) "Optimize for cold start performance"

# Use edge-native patterns
/orchestre:execute-task (MCP) "Implement KV-based session storage"
/orchestre:execute-task (MCP) "Add request coalescing for external APIs"

# Document learnings
/orchestre:document-feature (MCP) "Edge optimization patterns"

2. Global Distribution

# Configure regions
/configure-deployment "Set up multi-region"

# Handle geo-routing
/add-middleware "Geo-based routing"

3. Cost Optimization

• Use KV for frequently accessed data
• Implement smart caching strategies
• Minimize subrequest chains

Deployment

Wrangler Configuration

name = "my-api"
main = "src/index.ts"
compatibility_date = "2024-01-01"

[[kv_namespaces]]
binding = "CACHE"
id = "your-kv-id"

[[d1_databases]]
binding = "DB"
database_id = "your-d1-id"

Deploy Commands

# Development
wrangler dev

# Production
wrangler deploy

Template Features

Built-in Capabilities

The Cloudflare Hono template provides:

• Framework: Hono for modern, fast APIs
• Storage: KV, R2, D1, and Durable Objects configured
• Routing: Type-safe routing with Hono
• Middleware: Auth, CORS, rate limiting patterns
• Development: Wrangler configuration
• Types: Full TypeScript with Workers types

Technology Stack

• Runtime: Cloudflare Workers (V8 isolates)
• Framework: Hono (ultrafast web framework)
• Storage: KV (key-value), D1 (SQLite), R2 (objects)
• State: Durable Objects for coordination
• Development: Wrangler CLI
• Deployment: Zero-config edge deployment

Edge Constraints

• CPU: 10ms-50ms limits (varies by plan)
• Memory: 128MB limit
• Request Size: 100MB max
• Subrequests: 50-1000 (varies by plan)
• Script Size: 1MB compressed

Resources

• Cloudflare Workers Documentation
• Hono Framework
• Orchestre Documentation

See Also

• Orchestre Templates Overview
• Quick Start Guide
• All Templates