cloudflare-full-stack-scaffold

Cloudflare Full-Stack Scaffold

Complete, production-ready starter project for building full-stack applications on Cloudflare with React, Hono, AI SDK, and all Cloudflare services pre-configured.

When to Use This Skill

Use this skill when you need to:

• Start a new full-stack Cloudflare project in minutes instead of hours
• Build AI-powered applications with chat interfaces, RAG, or tool calling
• Have core Cloudflare services ready (D1, KV, R2, Workers AI)
• Opt-in to advanced features (Clerk Auth, AI Chat, Queues, Vectorize)
• Use modern best practices (Tailwind v4, shadcn/ui, AI SDK, React 19)
• Include planning docs and session handoff from the start
• Choose your AI provider (Workers AI, OpenAI, Anthropic, Gemini)
• Enable features only when needed with simple npm scripts
• Avoid configuration errors and integration issues

What This Skill Provides

Complete Scaffold Project

A fully working application you can copy, customize, and deploy immediately:

# Copy the scaffold
cp -r scaffold/ my-new-app/
cd my-new-app/

# Install dependencies
npm install

# Initialize core services (D1, KV, R2)
./scripts/init-services.sh

# Create database tables
npm run d1:local

# Start developing
npm run dev

Result: Full-stack app running in ~5 minutes with:

• ✅ Frontend and backend connected
• ✅ Core Cloudflare services configured (D1, KV, R2, Workers AI)
• ✅ AI SDK ready with multiple providers
• ✅ Planning docs and session handoff protocol
• ✅ Dark mode, theming, UI components
• ✅ Optional features (1 script each to enable):
• Clerk Auth (npm run enable-auth)
• AI Chat UI (npm run enable-ai-chat)
• Queues (npm run enable-queues)
• Vectorize (npm run enable-vectorize)

Scaffold Structure

scaffold/
├── package.json              # All dependencies (React, Hono, AI SDK, Clerk)
├── tsconfig.json            # TypeScript config
├── vite.config.ts           # Cloudflare Vite plugin
├── wrangler.jsonc           # All Cloudflare services configured
├── .dev.vars.example        # Environment variables template
├── .gitignore               # Standard ignores
├── README.md                # Project-specific readme
├── CLAUDE.md                # Project instructions for Claude
├── SCRATCHPAD.md            # Session handoff protocol
├── CHANGELOG.md             # Version history
├── schema.sql               # D1 database schema
│
├── docs/                    # Complete planning docs
│   ├── ARCHITECTURE.md
│   ├── DATABASE_SCHEMA.md
│   ├── API_ENDPOINTS.md
│   ├── IMPLEMENTATION_PHASES.md
│   ├── UI_COMPONENTS.md
│   └── TESTING.md
│
├── migrations/              # D1 migrations
│   └── 0001_initial.sql
│
├── src/                     # Frontend (React + Vite + Tailwind v4)
│   ├── main.tsx
│   ├── App.tsx
│   ├── index.css           # Tailwind v4 theming
│   ├── components/
│   │   ├── ui/             # shadcn/ui components
│   │   ├── ThemeProvider.tsx
│   │   ├── ProtectedRoute.tsx     # Auth (COMMENTED)
│   │   └── ChatInterface.tsx      # AI chat (COMMENTED)
│   ├── lib/
│   │   ├── utils.ts        # cn() utility
│   │   └── api-client.ts   # Fetch wrapper
│   └── pages/
│       ├── Home.tsx
│       ├── Dashboard.tsx
│       └── Chat.tsx        # AI chat page (COMMENTED)
│
└── backend/                 # Backend (Hono + Cloudflare)
    ├── src/
    │   └── index.ts        # Main Worker entry
    ├── middleware/
    │   ├── cors.ts
    │   └── auth.ts         # JWT (COMMENTED)
    ├── routes/
    │   ├── api.ts          # Basic API routes
    │   ├── d1.ts           # D1 examples
    │   ├── kv.ts           # KV examples
    │   ├── r2.ts           # R2 examples
    │   ├── ai.ts           # Workers AI (direct binding)
    │   ├── ai-sdk.ts       # AI SDK examples (multiple providers)
    │   ├── vectorize.ts    # Vectorize examples
    │   └── queues.ts       # Queues examples
    └── db/
        └── queries.ts      # D1 typed query helpers

Helper Scripts

scripts/setup-project.sh:

• Copies scaffold to new directory
• Renames project in package.json
• Initializes git repository
• Runs npm install
• Prompts to initialize services

scripts/init-services.sh:

• Creates D1 database via wrangler
• Creates KV namespace
• Creates R2 bucket
• Updates wrangler.jsonc with IDs
• (Queues and Vectorize created when enabled)

scripts/enable-auth.sh:

• Uncomments all Clerk auth patterns
• Enables ProtectedRoute component
• Enables auth middleware
• Prompts for Clerk API keys
• Updates .dev.vars

scripts/enable-ai-chat.sh:

• Uncomments ChatInterface component
• Uncomments Chat page
• Enables AI SDK UI patterns
• Adds chat route to App.tsx
• Prompts for AI provider API keys

scripts/enable-queues.sh:

• Uncomments Queues routes and bindings
• Enables async message processing
• Provides queue creation instructions
• Updates backend and config files

scripts/enable-vectorize.sh:

• Uncomments Vectorize routes and bindings
• Enables vector search and RAG
• Provides index creation instructions
• Configures embedding dimensions

Reference Documentation

references/quick-start-guide.md:

• 5-minute setup walkthrough
• First deployment guide
• Common customizations

references/service-configuration.md:

• Details on each Cloudflare service
• When to use each one
• Configuration options

references/ai-sdk-guide.md:

• AI SDK Core vs UI
• Provider switching patterns
• Streaming and tool calling
• RAG implementation

references/customization-guide.md:

• Removing unused services
• Adding new routes/pages
• Customizing theme
• Project structure best practices

references/enabling-auth.md:

• Clerk setup walkthrough
• JWT template configuration
• Testing auth flow

Key Integrations

1. AI SDK Integration (Three Approaches)

Direct Workers AI Binding (fastest):

// Already works, no API key needed
const result = await c.env.AI.run('@cf/meta/llama-3-8b-instruct', {
  messages: [{ role: 'user', content: 'Hello' }]
})

AI SDK with Workers AI (portable code, same infrastructure):

import { streamText } from 'ai'
import { createWorkersAI } from 'workers-ai-provider'

const workersai = createWorkersAI({ binding: c.env.AI })
const result = await streamText({
  model: workersai('@cf/meta/llama-3-8b-instruct'),
  messages: [{ role: 'user', content: 'Hello' }]
})

AI SDK with External Providers (OpenAI, Anthropic, Gemini):

import { openai } from '@ai-sdk/openai'
import { anthropic } from '@ai-sdk/anthropic'

// Switch providers in 1 line
const result = await streamText({
  model: openai('gpt-4o'),  // or anthropic('claude-sonnet-4-5')
  messages: [{ role: 'user', content: 'Hello' }]
})

AI SDK v5 UI - Chat Interface (COMMENTED, enable with script):

import { useChat } from '@ai-sdk/react'
import { DefaultChatTransport } from 'ai'
import { useState } from 'react'

function ChatInterface() {
  const [input, setInput] = useState('')
  const { messages, sendMessage, status } = useChat({
    transport: new DefaultChatTransport({
      api: '/api/ai-sdk/chat',
    }),
  })

  // Send message on Enter key
  const handleKeyDown = (e) => {
    if (e.key === 'Enter' && status === 'ready' && input.trim()) {
      sendMessage({ text: input })
      setInput('')
    }
  }

  // Render messages (v5 uses message.parts[])
  return (
    <div>
      {messages.map(m => (
        <div key={m.id}>
          {m.parts.map(part => {
            if (part.type === 'text') return <div>{part.text}</div>
          })}
        </div>
      ))}
      <input
        value={input}
        onChange={e => setInput(e.target.value)}
        onKeyDown={handleKeyDown}
        disabled={status !== 'ready'}
      />
    </div>
  )
}

2. Forms & Data Fetching (React Hook Form + Zod + TanStack Query)

Industry-Standard Libraries for Production Apps:

React Hook Form - Performant form state ma