cloudflare-full-stack-scaffold

What this skill does

# 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:

```bash
# 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):
```typescript
// 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):
```typescript
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):
```typescript
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):
```tsx
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 m