Cloudflare Workers + React Boilerplate Template

Deploy React apps to 300+ global locations for free. A complete starter kit with databases, AI integration, and CI/CD - all on Cloudflare's generous free tier. Simple architecture, no unnecessary complexity.

From portfolio sites to AI-powered SaaS - start simple and scale when you need to. Push to GitHub, deploy in seconds.

💡 First time building a website? Don't worry about the tech jargon. Run /start in Claude Code and answer a few questions - you'll be live in minutes. Claude handles the hard parts while you learn.

🎯 What Is This?

A free, production-ready starter kit for React apps that deploy to Cloudflare's global edge network. Everything you need to ship:

• React 19 + TypeScript + Vite - Fast development, type safety, instant hot reload
• API backend at the edge - Serverless functions that run near your users
• Optional databases - D1 (SQL) or KV (key-value) when you need them
• Optional AI integration - Claude API or Workers AI patterns included
• Automatic deploys - Push to GitHub → live in seconds
• Claude Code commands - /start, /add-ai-feature, /setup-database

Start with what you need. Add more when you're ready.

Perfect For

When to Use Something Else

💡 Simple static sites work great here! You get free global CDN, instant deploys, and room to add APIs/databases when you need them.

This template uses client-side rendering - your React app runs entirely in the browser.
React Router v7 and TanStack Start use server-side rendering - the server generates HTML before sending it to the browser.

Choose this template if: You're building dashboards, admin panels, internal tools, or apps behind a login.

Choose React Router v7 if: SEO is a priority - you'll get faster indexing, working social media previews, and better Core Web Vitals scores.

Both use the same @cloudflare/vite-plugin under the hood - the difference is in how your app renders.

💰 Free Tier Highlights

Everything in this template runs on Cloudflare's free tier:

GitHub Actions is also free for public repos (unlimited) or private repos (2,000 min/month).

No credit card required to start.

⚡ Quick Start

Prerequisites

• Node.js 22+ and npm (matches Cloudflare Workers Builds default)
• Cloudflare Account (sign up free)
• GitHub Account (for automated deployment)

🤖 Claude Code Setup (Recommended)

If you're using Claude Code, this is the fastest way to get started:

# 1. Clone your new repository (after clicking "Use this template")
git clone https://github.com/your-username/your-new-repo.git
cd your-new-repo

# 2. Install dependencies
npm install

# 3. Open in Claude Code and run:
/start

The /start wizard handles everything:

• ✅ Configure project name and metadata
• ✅ Set up Cloudflare credentials (Account ID, API token)
• ✅ Configure GitHub secrets for CI/CD deployment
• ✅ Optionally enable Claude GitHub Actions (@claude in PRs)
• ✅ Set up custom domain (optional)
• ✅ First deployment to production
• ✅ Guide you to your next feature

That's it! Claude Code walks you through each step interactively.

🛠️ Manual Setup (Alternative)

If you prefer to set up manually without Claude Code:

1️⃣ Create Your Project

Click "Use this template" on GitHub, then:

git clone https://github.com/your-username/your-new-repo.git
cd your-new-repo
npm install

2️⃣ Get Cloudflare Credentials

Account ID:

1. Log in to Cloudflare Dashboard
2. Go to Workers & Pages
3. Copy your Account ID from the right sidebar

API Token:

1. Go to API Tokens
2. Click "Create Token" → Use "Edit Cloudflare Workers" template
3. Copy the generated token immediately

3️⃣ Add GitHub Secrets

1. In your GitHub repo: Settings → Secrets and variables → Actions
2. Add CLOUDFLARE_ACCOUNT_ID with your account ID
3. Add CLOUDFLARE_API_TOKEN with your API token

4️⃣ Deploy

# Start local development
npm run dev

# Or push to main for automatic deployment
git add . && git commit -m "Initial setup" && git push origin main

Your app is now live! Check the Actions tab for your deployment URL.

🏗️ Architecture & Tech Stack

┌────────────────────────────────────────────────────────────┐
│                    CLOUDFLARE GLOBAL EDGE                  │
│                                                            │
│  ┌────────────────────┐         ┌──────────────────────┐   │
│  │   Static Assets    │         │  Cloudflare Worker   │   │
│  │   (React SPA)      │         │  (API Endpoints)     │   │
│  │                    │         │                      │   │
│  │  • React 19        │         │  • TypeScript        │   │
│  │  • Vite Build      │         │  • Edge Functions    │   │
│  │  • SPA Routing     │         │  • 0ms cold start    │   │
│  └────────────────────┘         └──────────────────────┘   │
│           │                              │                 │
│           └──────────────┬───────────────┘                 │
│                          │                                 │
│  ┌───────────────────────▼──────────────────────────────┐  │
│  │          CLOUDFLARE BINDINGS & SERVICES              │  │
│  │                                                      │  │
│  │  • D1 (SQLite Database)    • KV (Key-Value Store)    │  │
│  │  • R2 (Object Storage)     • Queues (Message Bus)    │  │
│  │  • Workers AI (Edge AI)    • AI Gateway (Caching)    │  │
│  │  • Analytics Engine        • Durable Objects         │  │
│  └──────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────┘

Core Technologies

Cloudflare Products Integrated

• Workers - Serverless edge compute (your API backend)
• D1 - Serverless SQLite database at the edge
• KV - Ultra-fast key-value storage
• R2 - S3-compatible object storage (setup helper included)
• Workers AI - Edge-native AI inference (examples included)
• AI Gateway - Caching & analytics for AI APIs (examples included)
• Sandbox SDK - Secure isolated code execution (Beta - documentation included)
• Queues - Message queue system (setup helper included)
• Analytics Engine - Custom analytics (setup helper included)

🚀 Deployment Options

This template supports three deployment methods to fit different workflows and budgets. Choose based on your repository visibility and usage patterns.

Deployment Methods Comparison

Free Tier Limits

Both Cloudflare and GitHub offer generous free tiers:

GitHub Actions (source):

Note: Windows runners use 2× minutes, macOS uses 10× minutes. Linux runners (used in this template) have no multiplier.

Cloudflare Workers (source):

Option 1: GitHub Actions (Default)

Best for: Public repositories, teams, complex build pipelines

This template comes pre-configured with GitHub Actions. Every push to main triggers automatic deployment.

Developer → git push main → GitHub Actions builds → Cloudflare deploys globally

Setup:

1. Add CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID to GitHub Secrets
2. Push to main - deployment is automatic

Pros:

• ✅ Unlimited minutes for public repos
• ✅ Full control over build pipeline
• ✅ Easy to add tests, linting, preview deploys
• ✅ Familiar GitHub workflow

Cons:

• ⚠️ 2,000 min/month limit for private repos (≈100-200 deploys)
• ⚠️ Requires GitHub Secrets setup

Option 2: Cloudflare Workers Builds (Native Git Integration)

Best for: Private repositories, avoiding GitHub Actions limits

Cloudflare can build and deploy directly from your GitHub/GitLab repo - no GitHub Actions needed.

Developer → git push → Cloudflare detects change → Builds & deploys

Setup:

1. Go to Cloudflare Dashboard → Workers & Pages
2. Click "Create" → "Import a repository"
3. Connect your GitHub account and select your repo
4. Configure build settings (Cloudflare auto-detects Vite projects)
5. Deploy!

Pros:

• ✅ 3,000 build minutes/month on free tier (separate from GitHub)
• ✅ No GitHub Actions minutes consumed
• ✅ Preview URLs for pull requests
• ✅ Simpler setup - no secrets to configure

Cons:

• ⚠️ 1 concurrent build on free tier
• ⚠️ Less customisable than GitHub Actions
• ⚠️ Can't run custom tests/linting in build pipeline

To switch to Cloudflare Builds:

1. Delete or disable .github/workflows/deploy.yml
2. Set up Workers Builds in Cloudflare Dashboard
3. Push to trigger first build

Option 3: Local Wrangler Deployment

Best for: Manual deployments, testing, CI/CD on other platforms

Deploy directly from your terminal using Wrangler CLI.

Developer → npm run deploy → Wrangler builds & deploys → Live globally

Setup:

# First time: Authenticate with Cloudflare
npx wrangler login

# Deploy anytime
npm run deploy

Pros:

• ✅ No CI/CD limits - deploy as often as you want
• ✅ Instant deployment feedback
• ✅ Works with any CI/CD platform (GitLab CI, CircleCI, Jenkins)
• ✅ Good for testing before committing

Cons:

• ⚠️ Manual process - not automated
• ⚠️ Requires Wrangler installed and authenticated
• ⚠️ No audit trail in GitHub

Recommendation by Scenario

Monitoring Your Usage

GitHub Actions:

• Go to your repo → Settings → Billing → Actions
• Or: Your profile → Settings → Billing → Actions

Cloudflare:

• Dashboard → Workers & Pages → Your Worker → Analytics

Pipeline Configuration (GitHub Actions - Default)

Defined in: .github/workflows/deploy.yml

Secrets Required (one-time setup):

• CLOUDFLARE_API_TOKEN - Workers deployment permission
• CLOUDFLARE_ACCOUNT_ID - Your Cloudflare account ID

Build Steps:

1. Install dependencies (npm install)
2. Compile TypeScript (tsc -b)
3. Build production bundle (vite build)
4. Deploy to Cloudflare Workers (wrangler deploy)

Result: Your app is live globally on Cloudflare's edge network (300+ cities)

🤖 Claude Code Integration

This template is optimised for AI-assisted development with Claude Code, featuring interactive slash commands that accelerate your workflow.

Available Slash Commands

Claude GitHub Actions

Enable @claude mentions in pull requests and issues to get AI-powered assistance directly in GitHub:

• Ask questions - @claude explain how authentication works
• Request reviews - @claude review this PR for security issues
• Implement changes - @claude add input validation to the form

Claude reads your code, follows your CLAUDE.md guidelines, and commits changes directly to your branch.

Quick setup: Run /start and select "Yes" when asked about Claude GitHub Actions.

📖 See docs/GITHUB_ACTIONS_CLAUDE.md for complete setup instructions.

Example Workflow

# 1. Complete setup in one command
/start
# Handles: project config, credentials, domain, first deployment

# 2. Add AI chat feature
/add-ai-feature
# Choose: Claude API → Streaming Chat
# Result: Complete chat UI + API endpoint generated

# 3. Add database for chat history
/setup-database
# Choose: D1 (SQL)
# Result: Database created, migrations generated, types updated

# 4. Generate implementation plan
/generate-prp "Save chat history to D1 database"

# 5. Execute the plan
/execute-prp PRPs/chat-history.md

See .claude/README.md for complete documentation.

Cloudflare Documentation MCP Server

This template includes the official Cloudflare Documentation MCP Server pre-configured (.mcp.json). Claude Code can search official Cloudflare docs to answer questions about Workers, D1, KV, R2, Durable Objects, and any other Cloudflare product.

Just ask Claude Code questions like:

• "How do I set up a D1 database?"
• "What are Workers KV limits?"
• "Show me R2 bucket examples"

🎨 Opinionated VS Code Defaults

This template includes sensible VS Code configuration out-of-the-box, optimised for Claude Code development.

Recommended Extensions (.vscode/extensions.json)

When you open the project, VS Code will prompt you to install:

Workspace Settings (.vscode/settings.json)

Pre-configured for a clean coding experience:

• Format on save with Prettier
• Terminal panel on the right - more vertical space for code
• Activity bar at top - compact, modern layout
• Minimap enabled - code overview on the right
• Search excludes node_modules, dist, .wrangler
• JSONC support for wrangler.json (allows comments)
• Syntax highlighting for .dev.vars secrets file

These defaults work great with Claude Code's terminal-focused workflow. Override any setting in your user preferences if needed.

🤖 AI Integration Features

Build AI-powered applications with zero infrastructure setup. This template includes ready-to-use patterns for integrating AI into your web app.

AI Options

Quick Start: Add AI

# Interactive AI setup wizard
/add-ai-feature

Choose your AI provider and feature type:

• ✅ Simple chat interface
• ✅ Streaming responses (real-time)
• ✅ Text completion/generation
• ✅ Embeddings for semantic search
• ✅ Image generation (Workers AI)

Working Examples Included

Explore examples/ai/ for complete implementations:

1. Simple Claude Chat - Basic chat with Claude API
2. Streaming Chat - Real-time streaming with Server-Sent Events
3. Workers AI Chat - Edge AI with Llama/Mistral models
4. AI Gateway Integration - Production caching & cost optimization

Each example includes:

• ✅ Complete React component (UI)
• ✅ Worker endpoint (API)
• ✅ TypeScript types
• ✅ Security best practices
• ✅ Setup documentation

Learn More

📖 AI_INTEGRATION.md - Comprehensive AI integration guide

💾 Database & Storage

Serverless, edge-native data storage with zero configuration and global replication.

Storage Options

Quick Start: Add Database

# Interactive database setup
/setup-database

This wizard will:

• Help you choose D1 (SQL) or KV (key-value)
• Create the database/namespace
• Update wrangler.jsonc configuration
• Generate TypeScript types
• Create migration files (D1)
• Provide example CRUD code

Working Examples Included

Explore examples/database/ for patterns:

1. D1 Contact Form - Complete CRUD with SQLite

   • Schema design
   • Migration files
   • SQL injection prevention
   • React form + Worker API

2. KV Sessions - Session management

   • Secure cookie handling
   • Session middleware
   • React auth provider
   • Login/logout flow

Learn More

📖 CLOUDFLARE_WORKERS.md - Complete Cloudflare Workers guide

📚 Examples & Reference Implementations

The examples/ directory contains production-ready code you can copy directly into your project.

Available Examples

AI Integration → examples/ai/

• Simple Claude Chat
• Streaming Chat (SSE)
• Workers AI Chat
• AI Gateway Integration

Database → examples/database/

• D1 Contact Form (SQL CRUD)
• KV Sessions (Auth)

How to Use Examples

Each example is self-contained and includes:

example-name/
├── README.md              # Setup guide
├── worker-endpoint.ts     # API code
├── Component.tsx          # React UI
├── types.ts              # TypeScript types
├── schema.sql            # Database schema (if applicable)
└── PRP.md                # Implementation plan

Integration steps:

1. Browse examples/ directory
2. Read the example's README
3. Copy code to your project (src/ for React, worker/ for API)
4. Update wrangler.jsonc with required bindings
5. Run npm run cf-typegen to generate types
6. Test with npm run dev

📖 examples/README.md - Complete integration guide

🛠️ Development Commands

# Development
npm run dev          # Start local dev server (http://localhost:5173)
npm run build        # Build for production
npm run preview      # Preview production build locally
npm run lint         # Run ESLint

# Testing
npm run test         # Run tests once
npm run test:watch   # Run tests in watch mode
npm run test:coverage # Run tests with coverage report

# Deployment
npm run deploy       # Build and deploy to Cloudflare Workers
git push origin main # Auto-deploy via GitHub Actions

# Cloudflare
npm run cf-typegen   # Generate TypeScript types for bindings

# Wrangler CLI (Cloudflare Workers)
npx wrangler d1 create <db-name>           # Create D1 database
npx wrangler d1 migrations apply <db-name> # Run migrations
npx wrangler kv namespace create <name>    # Create KV namespace
npx wrangler secret put <SECRET_NAME>      # Add secret
npx wrangler tail                          # Stream logs

🗂️ Project Structure

cloudflare-workers-react-boilerplate/
├── .github/
│   └── workflows/
│       ├── deploy.yml           # GitHub Actions CI/CD pipeline
│       └── claude.yml           # Claude GitHub Actions (after /start setup)
├── .claude/
│   ├── commands/                # Claude Code slash commands
│   │   ├── start.md
│   │   ├── generate-prp.md
│   │   ├── execute-prp.md
│   │   ├── add-ai-feature.md
│   │   ├── setup-database.md
│   │   ├── setup-sandbox.md
│   │   └── add-binding.md
│   ├── templates/               # Code generation templates
│   │   ├── claude-code-action.yml  # GitHub Actions workflow template
│   │   ├── domain-setup-reminder.md
│   │   └── ...
│   └── settings.json            # Claude Code tool permissions
├── examples/
│   ├── ai/                      # AI integration examples
│   │   ├── simple-claude-chat/
│   │   ├── streaming-chat/
│   │   ├── workers-ai-chat/
│   │   └── with-ai-gateway/
│   └── database/                # Database examples
│       ├── d1-contact-form/
│       └── kv-sessions/
├── src/
│   ├── App.tsx                  # Main React component
│   ├── App.test.tsx             # Example component tests
│   ├── main.tsx                 # React entry point
│   ├── test/
│   │   └── setup.ts             # Vitest test setup
│   └── ...                      # Your frontend code
├── worker/
│   └── index.ts                 # Cloudflare Worker (API endpoints + security headers)
├── public/                      # Static assets
├── .dev.vars.example            # Example local secrets template
├── .nvmrc                       # Node.js version (22)
├── vitest.config.ts             # Vitest testing configuration
├── wrangler.jsonc               # Cloudflare Workers configuration
├── vite.config.ts               # Vite configuration
├── tsconfig.json                # TypeScript config (root)
├── tsconfig.app.json            # TypeScript config (React app)
├── tsconfig.worker.json         # TypeScript config (Worker)
├── package.json                 # Dependencies and scripts
├── AI_INTEGRATION.md            # AI integration guide
├── CLOUDFLARE_WORKERS.md        # Cloudflare Workers guide
├── SANDBOX.md                   # Sandbox SDK guide
├── CLAUDE.md                    # Claude Code instructions
├── AGENTS.md                    # AI instructions (for other LLMs)
└── README.md                    # This file

🔐 Security Best Practices

This template follows security best practices:

✅ No secrets in code - All API keys stored in environment variables
✅ SQL injection prevention - Parameterised queries in all examples
✅ Input validation - All API endpoints validate inputs
✅ CORS configured - Proper cross-origin resource sharing
✅ Secrets management - Cloudflare secrets for sensitive data
✅ Type safety - TypeScript throughout for compile-time safety
✅ Security headers - CSP, X-Frame-Options, X-Content-Type-Options included
✅ Health check endpoint - /api/health for monitoring and uptime checks

Managing Secrets

Never commit secrets to Git!

Local development (copy .dev.vars.example to .dev.vars - gitignored):

cp .dev.vars.example .dev.vars
# Edit .dev.vars with your actual secret values
ANTHROPIC_API_KEY=sk-ant-your-key-here
DATABASE_URL=your-local-db

Production (Cloudflare secrets):

npx wrangler secret put ANTHROPIC_API_KEY
npx wrangler secret put DATABASE_URL

📖 Documentation

🤝 Contributing

Contributions are welcome! This is a community-driven template.

1. Fork this repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

You are free to:

• ✅ Use commercially
• ✅ Modify
• ✅ Distribute
• ✅ Use privately

🙏 Acknowledgments

Built with amazing open-source technologies:

• React - UI framework
• Vite - Build tool
• TypeScript - Language
• Cloudflare Workers - Edge compute platform
• Claude Code - AI pair programming

🚦 Status

💬 Support

• 📖 Documentation: Check the /docs folder and linked guides
• 💡 Examples: Explore the examples/ directory
• 🐛 Issues: Open an issue
• 💬 Discussions: GitHub Discussions