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
/startin Claude Code and answer a few questions - you'll be live in minutes. Claude handles the hard parts while you learn.
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.
| Use Case | Why This Template |
|---|---|
| Portfolio & personal sites | Free global hosting, looks professional, room to add features later |
| Side projects & MVPs | Ship in hours, not days. Database and auth patterns included |
| Learning Cloudflare Workers | Well-documented, beginner-friendly, with working examples |
| Keeping costs at zero | Generous free tiers: 100K requests/day, 5GB database, unlimited deploys |
| AI-powered apps | Claude API and Workers AI examples ready to copy |
| Requirement | Better Choice | Why |
|---|---|---|
| SEO-focused content sites | React Router v7 or TanStack Start | Server-side rendering gives you faster indexing, working social media previews, and better performance scores |
| Persistent Node.js server | Railway, Render, or VPS | Workers are stateless edge functions |
| WordPress/CMS content | Cloudflare Pages + headless CMS | Different architecture needed |
💡 Simple static sites work great here! You get free global CDN, instant deploys, and room to add APIs/databases when you need them.
🔧 Technical: How this compares to React Router v7 / TanStack Start
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.
| This Template | React Router v7 / TanStack Start |
|---|---|
| Browser renders the UI | Server renders the UI |
| Simpler architecture, fewer concepts | More features, more framework conventions |
| You choose your routing library | Routing built into the framework |
| You control data fetching | Framework controls data loading |
| No hydration complexity | Must handle server/client sync |
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.
Everything in this template runs on Cloudflare's free tier:
| Resource | Free Allowance | That's Enough For |
|---|---|---|
| Requests | 100,000/day | ~3 million/month |
| D1 Database | 5GB storage, 5M reads/day | Most small-to-medium apps |
| KV Storage | 1GB storage, 100K reads/day | Sessions, caching, config |
| R2 Storage | 10GB/month, zero egress fees | User uploads, file storage |
| Deploys | Unlimited | Push as often as you want |
| Custom domains | Unlimited | Your brand, free SSL |
GitHub Actions is also free for public repos (unlimited) or private repos (2,000 min/month).
No credit card required to start.
- Node.js 22+ and npm (matches Cloudflare Workers Builds default)
- Cloudflare Account (sign up free)
- GitHub Account (for automated deployment)
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:
/startThe /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 (
@claudein 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.
Click to expand manual setup instructions
If you prefer to set up manually without Claude Code:
Click "Use this template" on GitHub, then:
git clone https://github.com/your-username/your-new-repo.git
cd your-new-repo
npm installAccount ID:
- Log in to Cloudflare Dashboard
- Go to Workers & Pages
- Copy your Account ID from the right sidebar
API Token:
- Go to API Tokens
- Click "Create Token" → Use "Edit Cloudflare Workers" template
- Copy the generated token immediately
- In your GitHub repo: Settings → Secrets and variables → Actions
- Add
CLOUDFLARE_ACCOUNT_IDwith your account ID - Add
CLOUDFLARE_API_TOKENwith your API token
# Start local development
npm run dev
# Or push to main for automatic deployment
git add . && git commit -m "Initial setup" && git push origin mainYour app is now live! Check the Actions tab for your deployment URL.
┌────────────────────────────────────────────────────────────┐
│ 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 │ │
│ └──────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────┘
| Layer | Technology | Version | Purpose |
|---|---|---|---|
| Frontend | React | 19.2 | UI framework |
| Build Tool | Vite | 7.3 | Lightning-fast dev server & bundler |
| Language | TypeScript | 5.9 | Type-safe development |
| Testing | Vitest | 4.0 | Unit and component testing |
| Runtime | Cloudflare Workers | Latest | Serverless edge compute |
| Node.js | Node.js | 22+ | Development runtime (pinned in .nvmrc) |
| Package Manager | npm | Any | Dependency management |
| CI/CD | GitHub Actions | N/A | Automated deployment |
- 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)
This template supports three deployment methods to fit different workflows and budgets. Choose based on your repository visibility and usage patterns.
| Method | Best For | Setup | Automation | Limits |
|---|---|---|---|---|
| GitHub Actions | Public repos, teams | 5 min | On push to main |
Unlimited (public) / 2,000 min/month (private) |
| Cloudflare Workers Builds | Private repos, simplicity | 3 min | On push to branch | 3,000 build min/month (free) |
| Local Wrangler | Manual control, testing | 2 min | Manual | Unlimited |
Both Cloudflare and GitHub offer generous free tiers:
GitHub Actions (source):
| Repository Type | Minutes/Month | Storage |
|---|---|---|
| Public repos | ∞ Unlimited | Unlimited |
| Private repos | 2,000 minutes | 500 MB |
Note: Windows runners use 2× minutes, macOS uses 10× minutes. Linux runners (used in this template) have no multiplier.
Cloudflare Workers (source):
| Resource | Free Tier |
|---|---|
| Requests | 100,000/day |
| Build minutes | 3,000/month |
| Concurrent builds | 1 |
| Worker size | 3 MB |
| KV reads | 100,000/day |
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:
- Add
CLOUDFLARE_API_TOKENandCLOUDFLARE_ACCOUNT_IDto GitHub Secrets - 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
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:
- Go to Cloudflare Dashboard → Workers & Pages
- Click "Create" → "Import a repository"
- Connect your GitHub account and select your repo
- Configure build settings (Cloudflare auto-detects Vite projects)
- 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:
- Delete or disable
.github/workflows/deploy.yml - Set up Workers Builds in Cloudflare Dashboard
- Push to trigger first build
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 deployPros:
- ✅ 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
| Scenario | Recommended Method |
|---|---|
| Public repo, open source project | GitHub Actions (unlimited) |
| Private repo, frequent deploys (>100/month) | Cloudflare Workers Builds |
| Private repo, occasional deploys | GitHub Actions (fits in 2,000 min) |
| CI/CD on GitLab, Bitbucket, etc. | Local Wrangler in CI pipeline |
| Solo developer, manual control | Local Wrangler |
| Testing before push | Local Wrangler + GitHub Actions |
GitHub Actions:
- Go to your repo → Settings → Billing → Actions
- Or: Your profile → Settings → Billing → Actions
Cloudflare:
- Dashboard → Workers & Pages → Your Worker → Analytics
Defined in: .github/workflows/deploy.yml
Secrets Required (one-time setup):
CLOUDFLARE_API_TOKEN- Workers deployment permissionCLOUDFLARE_ACCOUNT_ID- Your Cloudflare account ID
Build Steps:
- Install dependencies (
npm install) - Compile TypeScript (
tsc -b) - Build production bundle (
vite build) - Deploy to Cloudflare Workers (
wrangler deploy)
Result: Your app is live globally on Cloudflare's edge network (300+ cities)
This template is optimised for AI-assisted development with Claude Code, featuring interactive slash commands that accelerate your workflow.
| Command | Description |
|---|---|
/start |
Complete project setup (run first!) - config, credentials, domain, deployment |
/generate-prp <feature> |
Create a comprehensive Product Requirement Plan |
/execute-prp <file> |
Implement a feature from a PRP |
/add-ai-feature |
Add AI capabilities (Claude API, Workers AI, AI Gateway) |
/setup-database |
Set up D1 (SQL) or KV (key-value) storage |
/setup-sandbox |
Configure Cloudflare Sandbox SDK for code execution |
/add-binding |
Add Cloudflare bindings (R2, Queues, etc.) |
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.
# 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.mdSee .claude/README.md for complete documentation.
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"
This template includes sensible VS Code configuration out-of-the-box, optimised for Claude Code development.
When you open the project, VS Code will prompt you to install:
| Extension | Purpose |
|---|---|
| ESLint | Code linting |
| Prettier | Code formatting |
| Vitest | Test explorer integration |
| Error Lens | Inline error display |
| Auto Rename Tag | JSX tag renaming |
| Path Intellisense | Import path autocomplete |
| npm Intellisense | npm module autocomplete |
| DotENV | .dev.vars syntax highlighting |
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.varssecrets file
These defaults work great with Claude Code's terminal-focused workflow. Override any setting in your user preferences if needed.
Build AI-powered applications with zero infrastructure setup. This template includes ready-to-use patterns for integrating AI into your web app.
| Option | Best For | Setup Time | Cost |
|---|---|---|---|
| Claude API | Advanced reasoning, long conversations | 2 min | Pay per token |
| Workers AI | Edge inference, cost-effective | 1 min | Included in Workers |
| AI Gateway | Production apps with caching | 5 min | Reduces AI costs 30-80% |
| Sandbox SDK | Safe AI code execution, REPLs | 5 min | Beta (free during beta) |
# Interactive AI setup wizard
/add-ai-featureChoose your AI provider and feature type:
- ✅ Simple chat interface
- ✅ Streaming responses (real-time)
- ✅ Text completion/generation
- ✅ Embeddings for semantic search
- ✅ Image generation (Workers AI)
Explore examples/ai/ for complete implementations:
- Simple Claude Chat - Basic chat with Claude API
- Streaming Chat - Real-time streaming with Server-Sent Events
- Workers AI Chat - Edge AI with Llama/Mistral models
- AI Gateway Integration - Production caching & cost optimization
Each example includes:
- ✅ Complete React component (UI)
- ✅ Worker endpoint (API)
- ✅ TypeScript types
- ✅ Security best practices
- ✅ Setup documentation
📖 AI_INTEGRATION.md - Comprehensive AI integration guide
Serverless, edge-native data storage with zero configuration and global replication.
| Storage | Type | Best For | Latency |
|---|---|---|---|
| D1 | SQL (SQLite) | Relational data, complex queries | <5ms |
| KV | Key-Value | Sessions, cache, config | <1ms |
| R2 | Object Storage | Files, images, videos | N/A |
# Interactive database setup
/setup-databaseThis wizard will:
- Help you choose D1 (SQL) or KV (key-value)
- Create the database/namespace
- Update
wrangler.jsoncconfiguration - Generate TypeScript types
- Create migration files (D1)
- Provide example CRUD code
Explore examples/database/ for patterns:
-
D1 Contact Form - Complete CRUD with SQLite
- Schema design
- Migration files
- SQL injection prevention
- React form + Worker API
-
KV Sessions - Session management
- Secure cookie handling
- Session middleware
- React auth provider
- Login/logout flow
📖 CLOUDFLARE_WORKERS.md - Complete Cloudflare Workers guide
The examples/ directory contains production-ready code you can copy directly into your project.
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)
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:
- Browse
examples/directory - Read the example's README
- Copy code to your project (
src/for React,worker/for API) - Update
wrangler.jsoncwith required bindings - Run
npm run cf-typegento generate types - Test with
npm run dev
📖 examples/README.md - Complete integration guide
# 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 logscloudflare-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
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
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-dbProduction (Cloudflare secrets):
npx wrangler secret put ANTHROPIC_API_KEY
npx wrangler secret put DATABASE_URL| Document | Description |
|---|---|
| README.md | This file - Overview and quick start |
| CLAUDE.md | Developer guidelines and AI coding instructions |
| AGENTS.md | AI guidelines for other LLMs (duplicate of CLAUDE.md) |
| AI_INTEGRATION.md | Complete AI integration guide |
| docs/GITHUB_ACTIONS_CLAUDE.md | Claude GitHub Actions for PR automation |
| SANDBOX.md | Cloudflare Sandbox SDK for code execution |
| CLOUDFLARE_WORKERS.md | Cloudflare Workers operations guide |
| docs/CONVENTIONS.md | British English and style conventions |
| .claude/README.md | Claude Code slash commands documentation |
| examples/README.md | How to use and integrate examples |
Contributions are welcome! This is a community-driven template.
- Fork this repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
You are free to:
- ✅ Use commercially
- ✅ Modify
- ✅ Distribute
- ✅ Use privately
Built with amazing open-source technologies:
- React - UI framework
- Vite - Build tool
- TypeScript - Language
- Cloudflare Workers - Edge compute platform
- Claude Code - AI pair programming
- 📖 Documentation: Check the
/docsfolder and linked guides - 💡 Examples: Explore the
examples/directory - 🐛 Issues: Open an issue
- 💬 Discussions: GitHub Discussions
⚡ Built with Cloudflare Workers • 🤖 Optimized for Claude Code • 🚀 Production Ready