cloudflare-full-stack-scaffold

Cloudflare フルスタック スキャフォールド

React、Hono、AI SDK を使用し、すべての Cloudflare サービスを事前設定した、フルスタックアプリケーション構築用の完全な本番環境対応スタータープロジェクトです。

このスキルを使う場面

次のような場合にこのスキルを使用します。

• 新しいフルスタック Cloudflare プロジェクトを数時間ではなく数分で開始する
• チャットインターフェース、RAG、ツール呼び出しを備えた AI 搭載アプリケーションを構築する
• 主要な 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 バケットを作成します
• wrangler.jsonc を ID で更新します
• （Queues と Vectorize は有効化時に作成されます）

scripts/enable-auth.sh：

• Clerk 認証のパターンのコメントをすべて解除します
• ProtectedRoute コンポーネントを有効にします
• 認証ミドルウェアを有効にします
• 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 テンプレートの設定
• 認証フローのテスト

主な統合機能

1. AI SDK の統合（3 つの方法）

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 ルートの例

Key-Value ストレージ（KV）：

• get／put／delete の例
• 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"
  }
}

トークン効率

シナリオ	Scaffold なし	Scaffold あり	削減率
初期セットアップ	約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%短縮）

防止できるよくある問題

問題	Scaffold による防止方法
サービスのバインディングエラー	すべてのバインディングが事前に設定され、テスト済みです
CORS エラー	ミドルウェアが正しい順序で設定されています
認証の競合状態	適切な読み込み状態のパターンが用意されています
フロントエンドとバックエンドの接続	Vite プラグインが正しく設定されています
AI SDK のセットアップに関する混乱	動作するサンプルが複数用意されています
計画ドキュメントの不足	docs/ の完全な構成が含まれています
環境変数の混同	コメント付きの .dev.vars.example で明確に示されています
マイグレーションの不足	サンプルを含む migrations/ ディレクトリが用意されています
ファイル構成の不統一	標準化され、テスト済みの構成です
データベースの型エラー	型付きクエリヘルパーが含まれています
テーマ設定	Tailwind v4 のテーマ設定が事前に構成されています
ビルドエラー	動作するビルド設定（vite + wrangler）が用意されています

防止できるエラーの合計：よくあるセットアップおよび統合エラーを12件以上

この Scaffold を使わない方がよい場合

• ❌ 静的サイトを構築する場合（バックエンドは不要）
• ❌ 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 - セッション引き継ぎプロトコル

---

覚えておいてください：この Scaffold は出発点であり、制約ではありません。必要に合わせてすべてをカスタマイズしてください。すでに統合パターンが一通り整った動作する基盤を用意することで、セットアップやデバッグにかかる時間を何時間も節約できることが、その価値です。