Cloudflare Worker Builder

プロジェクトの説明から Cloudflare Worker プロジェクトをスキャフォルドします。Hono ルーティング、Vite dev サーバー、Static Assets を備えたデプロイ可能なプロジェクトを生成します。

ワークフロー

ステップ 1: プロジェクトを理解する

適切なバインディングと構造を選択するためにプロジェクトについて質問します:

• アプリの機能は何か？(API のみ、SPA + API、ランディングページ)
• どのようなデータストレージか？(D1 データベース、R2 ファイル、KV キャッシュ、なし)
• 認証は必要か？(Clerk、better-auth、なし)
• カスタムドメインか workers.dev サブドメインか？

「データベース付き todo アプリ」のような簡潔な説明があれば十分です。

ステップ 2: プロジェクトをスキャフォルド

npm create cloudflare@latest my-worker -- --type hello-world --ts --git --deploy false --framework none
cd my-worker
npm install hono
npm install -D @cloudflare/vite-plugin vite

このスキルの assets/ ディレクトリからアセットファイルをコピーしてカスタマイズします:

• wrangler.jsonc — Worker 設定
• vite.config.ts — Vite + Cloudflare プラグイン
• src/index.ts — Static Assets フォールバック付き Hono アプリ
• package.json — スクリプトと依存関係
• tsconfig.json — TypeScript 設定
• public/index.html — SPA エントリーポイント

ステップ 3: バインディングを設定

プロジェクトのニーズに基づいて wrangler.jsonc にバインディングを追加します。Wrangler 4.45+ は初回デプロイ時にリソースを自動プロビジョニングします — 常に明示的な名前を指定してください:

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-11-11",
  "assets": {
    "directory": "./public/",
    "binding": "ASSETS",
    "not_found_handling": "single-page-application",
    "run_worker_first": ["/api/*"]
  },
  // 必要に応じて追加:
  "d1_databases": [{ "binding": "DB", "database_name": "my-app-db" }],
  "r2_buckets": [{ "binding": "STORAGE", "bucket_name": "my-app-files" }],
  "kv_namespaces": [{ "binding": "CACHE", "title": "my-app-cache" }]
}

ステップ 4: デプロイ

npm run dev           # http://localhost:8787 でローカル開発
wrangler deploy       # 本番環境にデプロイ

---

重要なパターン

エクスポート構文

// 正解 — このパターンを使用してください
export default app

// 間違い — "Cannot read properties of undefined" が発生します
export default { fetch: app.fetch }

ソース: honojs/hono #3955

Static Assets + API ルート

run_worker_first なしでは、SPA フォールバックが API ルートをインターセプトして、JSON の代わりに index.html を返します:

"assets": {
  "not_found_handling": "single-page-application",
  "run_worker_first": ["/api/*"]  // 重要
}

ソース: workers-sdk #8879

Vite 設定

import { defineConfig } from 'vite'
import { cloudflare } from '@cloudflare/vite-plugin'

export default defineConfig({ plugins: [cloudflare()] })

wrangler.jsonc の main フィールドを常に設定してください — Vite プラグインが必要とします。

スケジュール / Cron ハンドラー

cron トリガーを追加する場合は、明示的なエクスポートに切り替えてください:

export default {
  fetch: app.fetch,
  scheduled: async (event, env, ctx) => { /* ... */ }
}

---

リファレンスファイル

詳細なトラブルシューティングについてはこれらを参照してください:

• references/common-issues.md — 10 個のドキュメント化された問題とソース、修正方法
• references/architecture.md — ルート優先度、キャッシング、Workers RPC
• references/deployment.md — CI/CD、自動プロビジョニング、段階的なロールアウト