セットアップ

前提条件

ツール	バージョン
Bun	v1.3.11 以上（backend / frontend）
pnpm	v9 以上（Chrome 拡張）
Node.js	v22 以上（orval 実行時に使用）
Docker	ローカル PostgreSQL 用
uv	本ドキュメントのビルド用

README の make コマンドは使えない

各リポジトリの README にある make setup / make dev / make docker-up は、参照先の Makefile がワークスペースに存在しないため使えません。以下の各コマンドを直接実行してください。

手順

1. リポジトリのクローン

ワークスペース直下に 3 つのリポジトリを並べる構成を前提とする。

mkdir -p design && cd design
git clone <backend のリポジトリ URL> heineken-survey-design-backend
git clone <frontend のリポジトリ URL> heineken-survey-design-frontend
git clone <拡張のリポジトリ URL> Lab-web-extension

2. PostgreSQL の起動

backend は 127.0.0.1:55432 の PostgreSQL（DB 名 survey_design）に接続する。

docker run -d --name survey-design-db \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=survey_design \
  -p 55432:5432 postgres:16

3. backend のセットアップ

cd heineken-survey-design-backend
bun install
cp .env.example .env
bun run db:migrate    # マイグレーションの適用
bun run db:seed       # 開発用初期データの投入
bun run dev           # http://localhost:8787

.env の各項目を設定する。

変数名	説明	例
`DATABASE_URL`	DB 接続文字列	`postgres://postgres:postgres@127.0.0.1:55432/survey_design`
`SURVEY_ADMIN_EMAILS`	管理者のメールアドレス（カンマ区切り）	`admin@example.com,foo@example.com`
`SURVEY_IMPORT_API_KEY`	取り込み API の API キー。未設定ならキー認証は無効	`local-import-key`

4. frontend のセットアップ

cd ../heineken-survey-design-frontend
bun install
cp .env.example .env
bun run dev           # http://localhost:3000

.env の各項目を設定する。Google ログインを使うため、OAuth クライアントの発行が必要。

変数名	説明	例
`NEXTAUTH_URL`	next-auth のベース URL	`http://localhost:3000`
`NEXTAUTH_SECRET`	セッション暗号化キー	`openssl rand -base64 32` の出力
`GOOGLE_CLIENT_ID`	Google OAuth のクライアント ID	`xxxx.apps.googleusercontent.com`
`GOOGLE_CLIENT_SECRET`	Google OAuth のクライアントシークレット	`GOCSPX-...`
`NEXT_PUBLIC_API_URL`	backend API のベース URL	`http://localhost:8787`

http://localhost:3000 にアクセスして確認する。

5. Chrome 拡張のセットアップ

cd ../Lab-web-extension
pnpm install
pnpm dev

Chrome の拡張機能ページで「デベロッパーモード」を有効にし、「パッケージ化されていない拡張機能を読み込む」から build/chrome-mv3-dev を選択する。

6. ドキュメントのセットアップ

cd ../heineken-survey-design-docs
uv run mkdocs serve   # http://localhost:8000

よく使うコマンド

backend

コマンド	内容
`bun run dev`	開発サーバー（`--hot`）
`bun test`	全テスト
`bun test src/app.test.ts`	単一ファイル
`bun test -t "テスト名"`	名前フィルタ
`bun run typecheck`	`tsc --noEmit`
`bun run export:openapi`	`openapi.json` を書き出す（frontend の API client 生成の前提）
`bun run db:generate`	スキーマ変更からマイグレーション SQL を生成
`bun run db:studio`	DB の GUI を起動

frontend

コマンド	内容
`bun run dev`	開発サーバー
`bun run test`	Vitest
`bun run test -- path/to/file.test.tsx`	単一ファイル
`bun run lint` / `bun run lint:fix`	ESLint
`bun run format` / `bun run format:write`	Prettier
`bun run storybook`	Storybook（`http://localhost:6006`）
`bun run generate:api`	API client の再生成
`bun run new:component` / `bun run new:common`	コンポーネント雛形の生成

Chrome 拡張

コマンド	内容
`pnpm dev`	開発ビルド
`pnpm build`	本番ビルド
`pnpm test`	Vitest

API クライアントの再生成

backend の API を変更したら、次の順で frontend に反映する。

cd heineken-survey-design-backend && bun run export:openapi
cd ../heineken-survey-design-frontend && bun run generate:api

lib/api/generated.ts と lib/api/model/ は毎回作り直されるため 手編集禁止。

よくあるエラー

`make: *** No rule to make target` が出る

原因: README に書かれている Makefile がワークスペースに存在しない。

解決策: 上記の bun run / pnpm コマンドを直接使う。

backend 起動時に DB へ接続できない

原因: PostgreSQL が起動していない、または DATABASE_URL のポートが違う。

解決策:

docker ps | grep survey-design-db     # 起動しているか確認
cat .env | grep DATABASE_URL          # 55432 を指しているか確認

frontend の API 呼び出しが 401 になる

原因: Google ログインが済んでいない、または backend にユーザー情報ヘッダが渡っていない。

解決策: /login からログインし直す。backend 側は x-user-email と x-user-name の両方が必要。

`bun run generate:api` が失敗する

原因: backend の openapi.json が未更新、または orval が要求する Node.js が見つからない。