cloudflare-full-stack-integration

Cloudflare フルスタック統合パターン

React + Cloudflare Workers + Hono + Clerk 認証の本番環境で検証済みのパターンです。

このスキルを使用する場面

次のような場合に、このスキルを使用してください。

• React フロントエンドを Cloudflare Worker バックエンドに接続する
• フルスタックアプリで Clerk による認証を実装する
• 認証トークンを自動的に含める API 呼び出しを設定する
• フロントエンドとバックエンド間の CORS エラーを解決する
• 認証の読み込みに関する競合状態を防ぐ
• 環境変数を正しく設定する
• API ルートから D1 データベースにアクセスする
• 認証が必要な保護対象ルートを作成する

このスキルで提供されるもの

テンプレート

フロントエンド（templates/frontend/）：

• lib/api-client.ts - トークンを自動的に付与する Fetch ラッパー
• components/ProtectedRoute.tsx - 読み込み状態を備えた認証ゲートのパターン

バックエンド（templates/backend/）：

• middleware/cors.ts - 開発環境と本番環境向けの CORS 設定
• middleware/auth.ts - Clerk による JWT 検証
• routes/api.ts - すべてのパターンを統合した API ルートの例

設定（templates/config/）：

• wrangler.jsonc - バインディングを含む Workers の完全な設定
• .dev.vars.example - 環境変数の設定
• vite.config.ts - Cloudflare Vite プラグインの設定

リファレンス（references/）：

• common-race-conditions.md - 認証の読み込みに関する問題の完全ガイド

重要なアーキテクチャ上のポイント

1. @cloudflare/vite-plugin は同じポートで実行されます

重要なポイント：開発中、Worker とフロントエンドは同じポートで実行されます。

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

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

理由：Vite プラグインは開発サーバー内で workerd を直接使用して Worker を実行します。プロキシは不要です！

2. CORS はルートより前に適用する必要があります

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

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

3. 認証の読み込みは競合状態ではありません

多くの「競合状態」は、実際には isLoaded チェックの不足が原因です。

// ❌ WRONG: Calls API before token ready
useEffect(() => {
  fetch('/api/data') // 401 error!
}, [])

// ✅ CORRECT: Wait for auth to load
const { isLoaded, isSignedIn } = useSession()
useEffect(() => {
  if (!isLoaded || !isSignedIn) return
  fetch('/api/data') // Now token is ready
}, [isLoaded, isSignedIn])

4. 環境変数にはそれぞれ異なるルールがあります

フロントエンド（Vite）：

• VITE_ プレフィックスで始める必要があります
• .env ファイルで定義します
• アクセス方法：import.meta.env.VITE_VARIABLE_NAME

バックエンド（Workers）：

• プレフィックスは不要です
• .dev.vars ファイル（開発環境）または wrangler シークレット（本番環境）で定義します
• アクセス方法：env.VARIABLE_NAME

5. D1 バインディングは常に利用できます

D1 にはバインディング経由でアクセスするため、接続管理は不要です。

// ✅ CORRECT: Direct access via binding
const { results } = await env.DB.prepare('SELECT * FROM users').run()

// ❌ WRONG: No need to "connect" first
const connection = await env.DB.connect() // This doesn't exist!

ステップごとの統合ガイド

ステップ 1：プロジェクトのセットアップ

# Create project with Cloudflare Workers + React
npm create cloudflare@latest my-app
cd my-app

# Install dependencies
npm install hono @clerk/clerk-react @clerk/backend
npm install -D @cloudflare/vite-plugin @tailwindcss/vite

ステップ 2：Vite の設定

templates/config/vite.config.ts をプロジェクトのルートにコピーします。

ポイント：

• cloudflare() プラグインを含みます
• プロキシ設定は不要です
• インポートを簡潔にするためのパスエイリアスを設定します

ステップ 3：Wrangler の設定

templates/config/wrangler.jsonc をプロジェクトのルートにコピーします。

更新する項目：

• name をアプリ名に置き換えます
• 必要に応じて D1/KV/R2 バインディングを追加します
• API ルートには run_worker_first: ["/api/*"] を設定します

ステップ 4：環境変数の設定

.dev.vars を作成します（Git の追跡対象外）。

CLERK_PUBLISHABLE_KEY=pk_test_xxxxx
CLERK_SECRET_KEY=sk_test_xxxxx

フロントエンド用に .env を作成します。

VITE_CLERK_PUBLISHABLE_KEY=pk_test_xxxxx

ステップ 5：CORS ミドルウェアの追加

templates/backend/middleware/cors.ts をバックエンドにコピーします。

メインの Worker ファイルで適用します。

import { corsMiddleware } from './middleware/cors'

app.use('/api/*', (c, next) => corsMiddleware(c.env)(c, next))

重要：ルートを定義する前に適用してください！

ステップ 6：認証ミドルウェアの追加

templates/backend/middleware/auth.ts をバックエンドにコピーします。

保護対象ルートに適用します。

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

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

ステップ 7：API クライアントの設定

templates/frontend/lib/api-client.ts をフロントエンドにコピーします。

App コンポーネントで使用します。

import { useApiClient } from '@/lib/api-client'

function App() {
  useApiClient() // Set up token access
  return <YourApp />
}

ステップ 8：保護対象ルートの作成

templates/frontend/components/ProtectedRoute.tsx をコピーします。

認証が必要なページをラップするために使用します。

<ProtectedRoute>
  <Dashboard />
</ProtectedRoute>

ステップ 9：API ルートの作成

参考として templates/backend/routes/api.ts をコピーします。

すべてのルートに適用するパターン：

1. 最初に CORS を適用する
2. 保護対象ルートに認証ミドルウェアを適用する
3. JWT ペイロードからユーザー ID を取り出す
4. env バインディング経由で D1/KV/R2 にアクセスする
5. 型付き JSON レスポンスを返す

ステップ 10：統合のテスト

# Start dev server
npm run dev

# Both frontend and backend run on http://localhost:5173
# API routes: http://localhost:5173/api/*
# Frontend: http://localhost:5173/*

よくある問題と解決策

問題：401 Unauthorized エラー

症状：ユーザーがサインイン済みなのに、API 呼び出しが 401 で失敗する

原因：Clerk のセッションが読み込まれる前に API が呼び出されている

解決方法：API 呼び出しの前に isLoaded と isSignedIn を確認します

const { isLoaded, isSignedIn } = useSession()
if (!isLoaded || !isSignedIn) return // Wait for auth

参照：references/common-race-conditions.md

問題：CORS エラー

症状：「No 'Access-Control-Allow-Origin' header」エラーが発生する

原因：

1. CORS ミドルウェアが適用されていない
2. CORS ミドルウェアがルートの後に適用されている（順序が誤っている）
3. 本番環境でオリジンが許可されていない

解決方法：

// Apply BEFORE routes
app.use('/api/*', cors())
app.post('/api/data', handler)

本番環境では、ドメインに合わせて corsProdMiddleware を更新します。

問題：環境変数が機能しない

症状：フロントエンドまたはバックエンドで変数が undefined になる

フロントエンドでの解決方法：

• 変数名は必ず VITE_ で始める必要があります
• .env ファイルに記述する必要があります（.dev.vars ではありません）
• アクセス方法：import.meta.env.VITE_NAME

バックエンドでの解決方法：

• ローカル開発では、変数を .dev.vars に記述します
• 本番環境では、wrangler secret put NAME を使用します
• アクセス方法：env.NAME

問題：D1 クエリが失敗する

症状：データベースクエリでエラーが発生する

原因：

1. バインディングが wrangler.jsonc で設定されていない
2. SQL 構文エラー
3. パラメーター化クエリを使用していない

解決方法：

// ✅ CORRECT: Parameterized query
await env.DB.prepare('SELECT * FROM users WHERE id = ?')
  .bind(userId)
  .run()

// ❌ WRONG: SQL injection risk
await env.DB.prepare(`SELECT * FROM users WHERE id = ${userId}`).run()

問題：リクエストにトークンが付与されない

症状：バックエンドが Authorization ヘッダーのないリクエストを受け取る

原因：apiClient を使用していない、または useApiClient() フックを呼び出していない

解決方法：

1. App コンポーネントで useApiClient() を呼び出します
2. 生の fetch() の代わりに apiClient.get() を使用します

// In App.tsx
import { useApiClient } from '@/lib/api-client'
function App() {
  useApiClient() // MUST call this
  return <YourApp />
}

// In components
import { apiClient } from '@/lib/api-client'
const data = await apiClient.get('/api/data')

インテグレーションチェックリスト

デプロイの前に、以下を確認します。

フロントエンド：

• App コンポーネントで useApiClient() を呼び出している
• 保護されたページすべてが <ProtectedRoute> でラップされている
• API 呼び出しを行う前に isLoaded を確認している
• 環境変数が VITE_ で始まっている
• すべての API 呼び出しに apiClient を使用している

バックエンド：

• ルートより前に CORS ミドルウェアを適用している
• /api/protected/* ルートに認証ミドルウェアを適用している
• 環境変数を .dev.vars（開発環境）およびシークレット（本番環境）に設定している
• D1/KV/R2 バインディングを wrangler.jsonc で設定している
• D1 にパラメーター化クエリを使用している

設定：

• wrangler.jsonc に正しいバインディングが設定されている
• vite.config.ts に cloudflare() プラグインが含まれている
• .dev.vars が存在し、gitignore に追加されている
• フロントエンドの変数用に .env が存在する
• wrangler.jsonc に run_worker_first: ["/api/*"] が設定されている

パッケージのバージョン（2025-10-23 確認済み）

すべてのパッケージは、現在の安定版です。

{
  "@clerk/clerk-react": "5.53.3",
  "@clerk/backend": "2.19.0",
  "hono": "4.10.2",
  "vite": "7.1.11",
  "@cloudflare/vite-plugin": "1.13.14"
}

公式ドキュメントへのリンク

• Cloudflare Vite Plugin：https://developers.cloudflare.com/workers/vite-plugin/
• Hono：https://hono.dev/
• Clerk：https://clerk.com/docs
• D1 Database：https://developers.cloudflare.com/d1/
• Workers の CORS：https://developers.cloudflare.com/workers/examples/cors-header-proxy/

本番環境での実績

以下でパターンをテスト済みです。

• WordPress Auditor（https://wordpress-auditor.webfonts.workers.dev）
• 複数の Jezweb クライアントプロジェクト
• すべてのテンプレートで、2025-10-23 に動作を確認済み

トークン効率

このスキルを使わない場合：約 12k トークン ＋ 2～4 件のインテグレーションエラー このスキルを使う場合：約 4k トークン ＋ エラー 0 件 削減効果：トークン約 67％削減、エラーを 100％防止

---

覚えておきましょう：インテグレーションの問題の多くは、isLoaded の確認漏れか、ミドルウェアの順序違いです。テンプレートを使用し、手順に沿って進めてください！