ローカル開発環境

ローカル開発環境の詳細なセットアップ手順と、各サービスの個別設定について説明します。

ワークスペース構成

speakeasy/
├── apps/                 # SvelteKit フロントエンド
│   ├── counter/          # 店舗管理アプリ (port: 5174)
│   └── penthouse/        # システム管理アプリ (port: 5173)
├── gateways/             # API ゲートウェイ
│   ├── door/             # 認証ゲートウェイ
│   └── tap/              # 外部 API ゲートウェイ
├── services/             # バックエンドサービス
│   ├── proof/            # 認証 (port: 9004)
│   ├── vintage/          # 連絡先管理 (port: 9001)
│   ├── fizz/             # チャット (port: 9002)
│   ├── base/             # 基盤 (port: 9003)
│   └── bell/             # 通知 (port: 9004)
├── packages/             # 共有パッケージ
│   ├── cellar/           # DB (Drizzle ORM)
│   ├── vault/            # 認証 DB
│   ├── glass/            # UI コンポーネント
│   ├── jigger/           # 共有スキーマ (Zod)
│   └── garnish/          # デザイントークン
├── docs/                 # ドキュメント
│   ├── developer/        # 開発者ドキュメント (Astro)
│   ├── menu/             # Storybook (port: 5175)
│   └── card/             # API Reference (Scalar)
├── turbo.json            # Turborepo パイプライン
├── package.json          # ルートスクリプト
├── .dev.vars.example     # 環境変数テンプレート
└── CLAUDE.md             # AI コーディングガイド

開発ポート一覧

フロントエンド

アプリ	ポート	ホスト	備考
Penthouse	5173	0.0.0.0	HMR 無効（フリーズ回避）
Counter	5174	0.0.0.0	`dev-counter.plfumg.net` 許可
Storybook	5175	localhost	Playwright ブラウザテスト統合

バックエンドサービス

サービス	ポート	Inspector	Vite プラグイン
Vintage	9001	9231	cloudflare()
Fizz	9002	9230	cloudflare()
Base	9003	9232	cloudflare()
Proof	9004	9234	cloudflare()
Bell	9004	9231	cloudflare()

開発モード

1. ローカルモード（`bun dev`）

すべてのサービスをローカルで実行します。Cloudflare Workers のローカルエミュレーションを使用。

bun dev

Turborepo が全ワークスペースの dev タスクを並行実行します。

2. ハイブリッドモード（`bun dev:hybrid`）

フロントエンドはローカル、バックエンドはリモート dev 環境に接続:

bun dev:hybrid

内部的に turbo dev -- --remote --env dev を実行し、SvelteKit の adapter-cloudflare が platformProxy でリモートバインディングに接続します。

3. 選択起動モード

特定のアプリと依存サービスのみを起動:

# Counter + Fizz + Vintage
bun dev:counter

# Counter ハイブリッド（Fizz/Vintage はリモート）
bun dev:counter:hybrid

ハイブリッド開発の設定

.dev.vars で、ローカル実行するサービスを個別に制御できます:

# .dev.vars — コメント解除でローカル実行
# LOCAL_VINTAGE_URL=http://127.0.0.1:8787
# LOCAL_FIZZ_URL=http://127.0.0.1:8788
# LOCAL_DOOR_URL=http://127.0.0.1:8789
# LOCAL_BASE_URL=http://127.0.0.1:8790
# LOCAL_BELL_URL=http://127.0.0.1:8791

コメントアウトされたサービスはリモート dev 環境に接続します。

Turborepo パイプライン

turbo.json でタスク依存関係が定義されています:

タスク	依存	キャッシュ	永続
`build`	`^build`	あり	-
`dev`	なし	なし	あり
`lint`	`^build`	あり	-
`typecheck`	`^build`, `cf-typegen`	あり	-
`cf-typegen`	なし	あり	-
`deploy`	`build`	なし	-
`deploy:dev`	`^build`	なし	-

SvelteKit 設定

adapter-cloudflare

両アプリとも @sveltejs/adapter-cloudflare を使用:

adapter: cloudflare({
  platformProxy: {
    configPath: './wrangler.jsonc',
    persist: true
  }
});

platformProxy により、ローカル開発時も Service Bindings や KV/DO/R2 などの Cloudflare リソースにアクセスできます。

Remote Functions

SvelteKit の Remote Functions（*.remote.ts）を使用してサーバーサイドで RPC を呼び出します。asyncRunes が有効:

kit: {
  asyncRunes: true;
}

データベース開発

Drizzle Studio

ブラウザベースの DB 管理ツール:

cd packages/cellar

# dev 環境
bun run studio:dev

# 本番環境（読み取り注意）
bun run studio

マイグレーション

cd packages/cellar

# スキーマ変更後にマイグレーションファイル生成
bun run generate

# dev 環境に適用
bun run migrate:dev

# 本番環境に適用（デプロイ時）
bun run migrate:deploy

Cloudflare Workers 型生成

wrangler.jsonc のバインディング（Service Bindings, KV, DO, R2, Queue 等）を変更した場合:

bun cf-typegen

各サービスの worker-configuration.d.ts が自動生成され、TypeScript の型安全性が保たれます。

よくある問題

Penthouse の画面がフリーズする

Penthouse は HMR を無効化しています（vite.config.ts で hmr: false）。ファイル変更後はブラウザを手動でリロードしてください。

Service Bindings が見つからない

bun cf-typegen を実行して型を再生成
wrangler.jsonc のバインディング名を確認
ハイブリッドモードの場合、--remote --env dev が正しく渡されているか確認

ポート競合

strictPort: true が設定されているため、ポートが使用中の場合はエラーになります。前回のプロセスが残っていないか確認:

lsof -i :5174   # Counter のポート確認
kill -9 <PID>   # プロセスの終了