コンテンツにスキップ

Storefront ログインバイパス手順

Vite Storefront をローカルで動作確認する際、認証済みセッションを再現するためのバイパス機能をまとめます。Vendure 側にテスト顧客を作成し、フロントエンドから開発用の資格情報で自動ログインする流れです。現在の標準ガード構成（route beforeLoad guard + GraphQL client / request guard）を前提としつつ、開発時のみバイパスを有効化します。

前提

  • Vendure のシードが最新であること。
  • apps/vendure-server/src/seed-data.ts で以下のテスト顧客が作成されます。
    • 一般会員: test1@ritsubi-platform.com / DevCustomer123!
    • 直送会員: test2@ritsubi-platform.com / DevDirect123!
  • DB を初期化する必要がない場合は pnpm seed:test-customers を実行すると SuperAdmin/テスト顧客だけを再作成できます。
  • just dev / just dev-storefront-stack / just dev-storefront / just dev-storefront-bypass では、永続化済みローカル DB の schema / seed catalog / required baseline / test customer のドリフトを防ぐため、起動前に migrate:run と scripts/sync-runtime-baseline.ts が自動実行されます。 required baseline は依存カテゴリではなく、default channel や payment methods を含む独立監査対象です。 pnpm run dev:services + 個別起動の導線では自動同期されないため、必要に応じて明示実行してください。
  • 既存 DB にデータがない場合は pnpm exec nx run ritsubi-vendure-server:db:seed を実行してください。
  • Storefront 側で環境変数を設定できること（Secrets Manager + just または起動コマンドで指定）。

必要な環境変数

変数名 役割 既定値
STOREFRONT_AUTH_BYPASS バイパスの ON/OFF false
STOREFRONT_AUTH_BYPASS_EMAIL 自動ログインに使用するメールアドレス なし
STOREFRONT_AUTH_BYPASS_PASSWORD 同パスワード なし

認証ガードの前提（最新版）

  • route 認証ガード: src/runtime/auth-guard.ts を各 route の beforeLoad から呼び出して保護する。 session または vendure-session Cookie が無い場合は /auth/login?redirect=... へリダイレクトする。
  • クライアント側の GraphQL 再取得 / 認証状態更新: TanStack Query と refreshCustomer() を正本とし、401/403 や認可エラーは request-time guard と各 mutation/query の失敗処理からログイン導線へ戻す。
  • クライアント側ガードの役割: AuthGate は「パスワード変更必須フロー」などの補助のみ。ページ個別の未ログイン用UIは撤廃（例: /account/favorites は未ログイン時に即リダイレクト）。
  • 認証例外ルート: /auth 配下は server guard の対象外。再設定導線として /auth/password-reset と /auth/reset-password?token=... が有効です。（/auth/password-reset/complete は現行運用では使いません。）

バイパスを有効にすると、上記ガードを通過できる開発用セッションを Worker API （POST /api/auth-bypass）から自動生成します。local origin（localhost / *.localhost）でのみ有効であり、本番・ステージング・preview・公開 URL では利用できません。

最小構成では環境変数として以下を設定すれば動作します。

STOREFRONT_AUTH_BYPASS=true
VITE_PUBLIC_STOREFRONT_AUTH_BYPASS=enabled
STOREFRONT_AUTH_BYPASS_EMAIL=test1@ritsubi-platform.com
STOREFRONT_AUTH_BYPASS_PASSWORD=DevCustomer123!

起動コマンド

Storefront の bypass 起動は just レシピを正本にしています。

just dev-storefront-bypass
  • STOREFRONT_AUTH_BYPASS=true と VITE_PUBLIC_STOREFRONT_AUTH_BYPASS=enabled を付与した状態で Vite dev server を起動します。
  • 初回アクセス時に /api/auth-bypass が Worker API で GraphQL の login ミューテーションを実行し、Vendure セッション Cookie を取得してから activeCustomer/activeOrder をフェッチします。
  • 通常の購入フロー（お気に入り、カート投入、チェックアウト）がそのまま利用できます。

VS Code タスク

ルートの .vscode/tasks.json からは日常導線のみを公開しています。認証バイパスが必要な場合は Storefront: Auth Bypass (localhost) タスクを実行してください。 just local-storefront-bypass と同等の開発サーバーが立ち上がります。

CLI では just dev-storefront-bypass を利用してください。

  • just dev-storefront-bypass / just local-storefront-bypass は、STOREFRONT_AUTH_BYPASS_EMAIL / STOREFRONT_AUTH_BYPASS_PASSWORD が未設定なら seed 済みの一般会員 test1@ritsubi-platform.com / DevCustomer123! を補完します。
  • 別のテスト顧客で確認したい場合は、同名の server-only 環境変数を明示指定して上書きしてください。

注意事項

  1. local origin 専用: STOREFRONT_AUTH_BYPASS は開発専用フラグです。localhost / *.localhost 以外では Worker / browser ともに bypass を開きません。本番ビルドや Cloudflare Workers デプロイ時には false のままにしてください。
  2. セキュリティ: 資格情報は server-only の環境変数として渡し、VITE_PUBLIC_* へ載せないでください。共有リポジトリや公開ログに秘密情報を残さないでください。
  3. シードアカウントの維持: 自動ログインは Vendure 上のユーザー情報に依存します。DB リセット後は必ず db:seed を実行し、必要に応じて pnpm seed:test-customers で SuperAdmin/テスト顧客を再投入してください。

参考

  • Vendure シード手順: /apps/vendure-server/src/seed-data.ts
  • Storefront 実装ガイド: /docs/03-implementation/frontend/index.md