cloudflare-full-stack-scaffold

Cloudflare 全栈脚手架

完整、可用于生产环境的入门项目，用于在 Cloudflare 上构建全栈应用，已预配置 React、Hono、AI SDK 和所有 Cloudflare 服务。

何时使用此技能

在以下情况使用此技能：

• 在几分钟而非几小时内启动新的 Cloudflare 全栈项目
• 构建 AI 驱动的应用，包含聊天界面、RAG 或工具调用
• 预先配置核心 Cloudflare 服务（D1、KV、R2、Workers AI）
• 选择启用高级功能（Clerk Auth、AI Chat、Queues、Vectorize）
• 采用现代最佳实践（Tailwind v4、shadcn/ui、AI SDK、React 19）
• 从一开始就包含规划文档和会话交接
• 选择 AI 提供商（Workers AI、OpenAI、Anthropic、Gemini）
• 仅在需要时启用功能，只需运行简单的 npm 脚本
• 避免配置错误和集成问题

此技能提供的内容

完整的脚手架项目

一个可立即复制、自定义并部署的完整应用：

# 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

结果：约 5 分钟即可运行全栈应用，包含：

• ✅ 前端和后端已连接
• ✅ 核心 Cloudflare 服务已配置（D1、KV、R2、Workers AI）
• ✅ AI SDK 已就绪，支持多个提供商
• ✅ 规划文档和会话交接协议
• ✅ 深色模式、主题和 UI 组件
• ✅ 可选功能（每项功能只需运行 1 个脚本即可启用）：
  • 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/
├── 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

辅助脚本

scripts/setup-project.sh：

• 将脚手架复制到新目录
• 重命名 package.json 中的项目
• 初始化 git 仓库
• 运行 npm install
• 提示是否初始化服务

scripts/init-services.sh：

• 通过 wrangler 创建 D1 数据库
• 创建 KV 命名空间
• 创建 R2 存储桶
• 使用 ID 更新 wrangler.jsonc
• （启用 Queues 和 Vectorize 时创建）

scripts/enable-auth.sh：

• 取消所有 Clerk Auth 模式的注释
• 启用 ProtectedRoute 组件
• 启用 Auth 中间件
• 提示输入 Clerk API 密钥
• 更新 .dev.vars

scripts/enable-ai-chat.sh：

• 取消 ChatInterface 组件的注释
• 取消 Chat 页面的注释
• 启用 AI SDK UI 模式
• 向 App.tsx 添加聊天路由
• 提示输入 AI 提供商 API 密钥

scripts/enable-queues.sh：

• 取消 Queues 路由和绑定的注释
• 启用异步消息处理
• 提供队列创建说明
• 更新后端和配置文件

scripts/enable-vectorize.sh：

• 取消 Vectorize 路由和绑定的注释
• 启用向量搜索和 RAG
• 提供索引创建说明
• 配置嵌入维度

参考文档

references/quick-start-guide.md：

• 5 分钟设置指南
• 首次部署指南
• 常见自定义项

references/service-configuration.md：

• 各项 Cloudflare 服务的详细信息
• 每项服务的适用场景
• 配置选项

references/ai-sdk-guide.md：

• AI SDK Core 与 UI
• 提供商切换模式
• 流式传输和工具调用
• RAG 实现

references/customization-guide.md：

• 移除未使用的服务
• 添加新路由和页面
• 自定义主题
• 项目结构最佳实践

references/enabling-auth.md：

• Clerk 设置指南
• JWT 模板配置
• 测试 Auth 流程

关键集成

1. AI SDK 集成（三种方式）

直接使用 Workers AI 绑定（最快）：

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

使用 Workers AI 的 AI SDK（代码可移植，基础设施不变）：

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（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 - 聊天界面（已注释，可运行脚本启用）：

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. 表单与数据获取（React Hook Form + Zod + TanStack Query）

适用于生产应用的行业标准库：

React Hook Form - 高性能表单状态管理：

import { useForm } from 'react-hook-form'
import { zodResolver } from '@hookform/resolvers/zod'

const form = useForm({
  resolver: zodResolver(userSchema), // Zod validation
})

<input {...register('name')} />
{errors.name && <span>{errors.name.message}</span>}

Zod v4 - 以 TypeScript 为先的架构验证：

// Define schema once
const userSchema = z.object({
  name: z.string().min(2),
  email: z.string().email(),
  age: z.number().int().positive().optional(),
})

// Infer TypeScript type
type User = z.infer<typeof userSchema>

// Use in frontend (React Hook Form)
resolver: zodResolver(userSchema)

// Use in backend (same schema!)
const validated = userSchema.parse(requestBody)

TanStack Query v5 - 智能数据获取与缓存：

// Fetch data with automatic caching
const { data, isLoading } = useQuery({
  queryKey: ['users'],
  queryFn: () => apiClient.get('/api/users'),
})

// Update data with mutations
const mutation = useMutation({
  mutationFn: (newUser) => apiClient.post('/api/users', newUser),
  onSuccess: () => {
    queryClient.invalidateQueries({ queryKey: ['users'] })
  },
})

全栈验证模式：

• ✅ 在 shared/schemas/ 中定义架构（单一事实来源）
• ✅ 前端即时验证（React Hook Form + Zod）
• ✅ 后端安全验证（使用相同的 Zod 架构）
• ✅ 自动推断 TypeScript 类型
• ✅ 只需更新一次验证规则，即可在各处生效

完整可运行示例：

• 带表单的个人资料页面：/profile 路由
• 带查询功能的仪表板：/dashboard 路由
• 表单组件：src/components/UserProfileForm.tsx
• 后端验证：backend/routes/forms.ts
• 共享架构：shared/schemas/userSchema.ts

参阅 references/supporting-libraries-guide.md，获取完整指南。

3. 预配置的所有 Cloudflare 服务

数据库（D1）：

• 包含示例表的架构文件
• 迁移目录
• 类型化查询辅助函数
• CRUD 路由示例

键值存储（KV）：

• 获取／写入／删除示例
• TTL 模式
• 批量操作

对象存储（R2）：

• 上传／下载示例
• 预签名 URL
• 大文件流式传输

AI 推理（Workers AI）：

• 文本生成
• 嵌入
• 图像生成（Stable Diffusion）

向量数据库（Vectorize）：

• 插入／查询嵌入
• RAG 模式
• 相似度搜索

消息队列：

• 生产者示例
• 消费者模式
• 批处理

3. 可选的 Clerk 身份验证

已包含所有身份验证模式，但均已注释——取消注释即可启用：

./scripts/enable-auth.sh
# Prompts for Clerk keys, uncomments all patterns

启用的内容：

• 前端：ProtectedRoute 组件、api-client 中的身份验证
• 后端：JWT 验证中间件
• 受保护的 API 路由
• 身份验证加载状态
• 会话管理

4. 规划文档 + 会话交接协议

docs/ 目录——完整的规划结构：

• ARCHITECTURE.md：系统设计
• DATABASE_SCHEMA.md：D1 架构文档
• API_ENDPOINTS.md：所有路由的文档
• IMPLEMENTATION_PHASES.md：分阶段构建方案
• UI_COMPONENTS.md：组件层级结构
• TESTING.md：测试策略

SCRATCHPAD.md——会话交接协议：

• 当前阶段跟踪
• 进度检查点
• 后续操作
• 规划文档参考

使用指南

快速开始（5 分钟）

# 1. Copy scaffold
cd /path/to/skills/cloudflare-full-stack-scaffold
cp -r scaffold/ ~/projects/my-new-app/
cd ~/projects/my-new-app/

# 2. Run setup
npm install

# 3. Initialize Cloudflare services
npx wrangler d1 create my-app-db
npx wrangler kv:namespace create my-app-kv
npx wrangler r2 bucket create my-app-bucket
npx wrangler vectorize create my-app-index --dimensions=1536
npx wrangler queues create my-app-queue

# 4. Update wrangler.jsonc with IDs from step 3

# 5. Create D1 tables
npx wrangler d1 execute my-app-db --local --file=schema.sql

# 6. Start dev server
npm run dev

访问：http://localhost:5173

启用身份验证（可选）

./scripts/enable-auth.sh
# Prompts for Clerk publishable and secret keys
# Uncomments all auth patterns
# Updates .dev.vars

npm run dev

启用 AI 聊天界面（可选）

./scripts/enable-ai-chat.sh
# Uncomments ChatInterface component
# Uncomments Chat page
# Prompts for OpenAI/Anthropic API keys (optional)

npm run dev

访问：http://localhost:5173/chat

部署到生产环境

# Build
npm run build

# Deploy
npx wrangler deploy

# Migrate production database
npx wrangler d1 execute my-app-db --remote --file=schema.sql

# Set production secrets
npx wrangler secret put CLERK_SECRET_KEY
npx wrangler secret put OPENAI_API_KEY

自定义模式

移除未使用的服务

不需要 Vectorize？

1. 删除 backend/routes/vectorize.ts
2. 从 wrangler.jsonc 中移除 vectorize 绑定
3. 从 vite.config.ts 的 cloudflare 插件中移除
4. 从 backend/src/index.ts 中移除路由注册

添加新的 API 路由

// backend/routes/my-feature.ts
import { Hono } from 'hono'

export const myFeatureRoutes = new Hono()

myFeatureRoutes.get('/hello', (c) => {
  return c.json({ message: 'Hello from my feature!' })
})

// backend/src/index.ts
import { myFeatureRoutes } from './routes/my-feature'
app.route('/api/my-feature', myFeatureRoutes)

切换 AI 提供商

// Change this line:
model: openai('gpt-4o'),

// To this:
model: anthropic('claude-sonnet-4-5'),

// Or this:
model: google('gemini-2.5-flash'),

// Or use Workers AI:
const workersai = createWorkersAI({ binding: c.env.AI })
model: workersai('@cf/meta/llama-3-8b-instruct'),

自定义主题

所有主题设置都在 src/index.css 中：

:root {
  --background: hsl(0 0% 100%);  /* Change colors here */
  --foreground: hsl(0 0% 3.9%);
  --primary: hsl(220 90% 56%);
  /* etc */
}

架构亮点

前端与后端连接

关键要点：Vite 插件会在与 Vite 相同的端口上运行你的 Worker。

// ✅ CORRECT: Use relative URLs
fetch('/api/data')

// ❌ WRONG: Don't use absolute URLs
fetch('http://localhost:8787/api/data')

无需配置代理！

环境变量

前端（.env）：

VITE_CLERK_PUBLISHABLE_KEY=pk_test_xxx

后端（.dev.vars）：

CLERK_SECRET_KEY=sk_test_xxx
OPENAI_API_KEY=sk-xxx

CORS 配置

重要：必须在路由之前应用 CORS 中间件：

// ✅ CORRECT ORDER
app.use('/api/*', corsMiddleware)
app.post('/api/data', handler)

// ❌ WRONG - Will cause CORS errors
app.post('/api/data', handler)
app.use('/api/*', corsMiddleware)

身份验证模式（启用时）

前端：发起 API 调用前，先检查 isLoaded：

const { isLoaded, isSignedIn } = useSession()

useEffect(() => {
  if (!isLoaded) return  // Wait for auth
  fetch('/api/protected').then(/* ... */)
}, [isLoaded])

后端：JWT 验证中间件：

import { jwtAuthMiddleware } from './middleware/auth'

app.use('/api/protected/*', jwtAuthMiddleware)

包含的依赖项

{
  "dependencies": {
    "react": "^19.2.0",
    "react-dom": "^19.2.0",
    "hono": "^4.10.2",
    "@cloudflare/vite-plugin": "^1.13.14",

    "ai": "^5.0.76",
    "@ai-sdk/openai": "^1.0.0",
    "@ai-sdk/anthropic": "^1.0.0",
    "@ai-sdk/google": "^1.0.0",
    "workers-ai-provider": "^2.0.0",
    "@ai-sdk/react": "^1.0.0",

    "@clerk/clerk-react": "^5.53.3",
    "@clerk/backend": "^2.19.0",

    "tailwindcss": "^4.1.14",
    "@tailwindcss/vite": "^4.1.14",
    "class-variance-authority": "^0.7.0",
    "clsx": "^2.1.1",
    "tailwind-merge": "^2.5.4",

    "zod": "^3.24.1",
    "react-hook-form": "^7.54.2",
    "@hookform/resolvers": "^3.9.1",

    "@tanstack/react-query": "^5.62.11",

    "@radix-ui/react-slot": "^1.1.1",
    "@radix-ui/react-dropdown-menu": "^2.1.4"
  },
  "devDependencies": {
    "@types/react": "^19.0.0",
    "@types/react-dom": "^19.0.0",
    "typescript": "^5.7.2",
    "vite": "^7.1.11",
    "wrangler": "^4.0.0"
  }
}

令牌效率

场景	不使用脚手架	使用脚手架	节省
初始设置	~18-22k 个令牌	~3-5k 个令牌	~80%
服务配置	~8-10k 个令牌	0 个令牌（已完成）	100%
前后端连接	~5-7k 个令牌	0 个令牌（已完成）	100%
AI SDK 设置	~4-6k 个令牌	0 个令牌（已完成）	100%
身份验证集成	~6-8k 个令牌	~500 个令牌	~90%
规划文档	~3-5k 个令牌	0 个令牌（已包含）	100%
总计	~44-58k 个令牌	~3-6k 个令牌	~90%

节省时间：3-4 小时 → 5-10 分钟（快约 95%）

可预防的常见问题

问题	脚手架如何预防
服务绑定错误	所有绑定均已预先配置并测试
CORS 错误	中间件顺序正确
身份验证竞争条件	采用恰当的加载状态模式
前后端连接	Vite 插件配置正确
AI SDK 设置混乱	提供多个可运行示例
缺少规划文档	已包含完整的 docs/ 结构
环境变量混淆	.dev.vars.example 清晰明了，附有注释
缺少迁移文件	migrations/ 目录中包含示例
文件结构不一致	采用标准且经过测试的结构
数据库类型错误	已包含类型化查询辅助函数
主题配置	已预先配置 Tailwind v4 主题
构建错误	提供可用的构建配置（vite + wrangler）

预防的错误总数：12+ 个常见设置和集成错误

不适合使用此脚手架的情况

• ❌ 构建静态网站（不需要后端）
• ❌ 使用 Next.js、Remix 或其他元框架
• ❌ 需要 SSR（使用框架专用的 Cloudflare 适配器）
• ❌ 构建仅含后端的 API（不需要前端）
• ❌ 极其简单的单页应用

对于这些情况：请使用精简模板或官方框架起始项目。

生产环境依据

基于：

• Cloudflare 官方 agents-starter 模板（AI SDK 模式）
• cloudflare-full-stack-integration 技能（经过测试的前后端模式）
• session-handoff-protocol 技能（规划文档 + SCRATCHPAD.md）
• tailwind-v4-shadcn 技能（UI 组件模式）
• 多个 Jezweb 生产项目

已验证的软件包版本：2025-10-23

兼容：

• Cloudflare Workers（生产环境）
• Wrangler 4.0+
• Node.js 18+
• npm/pnpm/yarn

快速参考

设置新项目：

cp -r scaffold/ my-app/
cd my-app/
npm install
# Follow quick-start-guide.md

启用身份验证：

./scripts/enable-auth.sh

启用 AI 聊天：

./scripts/enable-ai-chat.sh

部署：

npm run build
npx wrangler deploy

关键文件：

• wrangler.jsonc - 服务配置
• vite.config.ts - 构建配置
• .dev.vars.example - 环境变量模板
• docs/ARCHITECTURE.md - 系统设计
• SCRATCHPAD.md - 会话交接协议

---

请记住：此脚手架是一个起点，而非限制。请根据需求自定义所有内容。它的价值在于提供一个可用的基础，其中已包含所有集成模式，能为你节省数小时的设置和调试时间。