コンテンツにスキップ

Storefront ログインバイパス手順

Next.js Storefront をローカルで動作確認する際、

認証済みセッションを再現するためのバイパス機能をまとめます。

Vendure 側にテスト顧客を作成し、

フロントエンドから開発用の資格情報で自動ログインする流れです。

現在の標準ガード構成（サーバー全体ガード + Apollo認証エラーハンドリング）を前提としつつ、

開発時のみバイパスを有効化します。

前提

  • Vendure のシードが最新であること。
  • apps/vendure-server/src/seed-data.ts で以下のテスト顧客が作成されます。
    • 一般会員: test1@ritsubi.mail-box.ne.jp / DevCustomer123!
    • 直送会員: test2@ritsubi.mail-box.ne.jp / DevDirect123!
  • DB を初期化する必要がない場合は pnpm seed:test-customers を実行すると SuperAdmin/テスト顧客だけを再作成できます。
  • 既存 DB にデータがない場合は pnpm --filter ritsubi-vendure-server run db:seed を実行してください。
  • Next.js 側で .env.local などを用意できる権限があること。

必要な環境変数

変数名 役割 既定値
NEXT_PUBLIC_STOREFRONT_AUTH_BYPASS バイパスの ON/OFF false
NEXT_PUBLIC_STOREFRONT_AUTH_BYPASS_EMAIL 自動ログインに使用するメールアドレス dev-bypass@ritsubi.mail-box.ne.jp
NEXT_PUBLIC_STOREFRONT_AUTH_BYPASS_PASSWORD 同パスワード DevCustomer123!
NEXT_PUBLIC_STOREFRONT_AUTH_BYPASS_CUSTOMER_ID バイパス時に期待する顧客ID DEV-BYPASS-CUSTOMER
NEXT_PUBLIC_STOREFRONT_AUTH_BYPASS_FIRST_NAME UI 表示用の名 開発
NEXT_PUBLIC_STOREFRONT_AUTH_BYPASS_LAST_NAME UI 表示用の姓 テスター
NEXT_PUBLIC_STOREFRONT_AUTH_BYPASS_CUSTOMER_NUMBER UI 表示用の顧客番号 DEV-BYPASS

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

  • サーバー側グローバルガード: src/middleware.ts で全ページを保護。session または vendure-session Cookie が無い場合は /auth/login?redirect=... へ 307 リダイレクト。/auth や静的アセットのみ通過。
  • Apollo認証エラーハンドリング: packages/sdk/shop/src/apollo-config.ts で GraphQL/HTTP の 401/403・FORBIDDEN/UNAUTHENTICATED を検知したらクッキー削除＋ログインへ強制遷移。
  • クライアント側ガードの役割: AuthGate は「パスワード変更必須フロー」などの補助のみ。ページ個別の未ログイン用UIは撤廃（例: /account/favorites は未ログイン時に即リダイレクト）。

バイパスを有効にすると、上記ガードを通過できる開発用セッションを自動生成します。本番・ステージングでは必ず OFF にしてください。

最小構成では .env.local に以下を追記すれば動作します。

NEXT_PUBLIC_STOREFRONT_AUTH_BYPASS=true
NEXT_PUBLIC_STOREFRONT_AUTH_BYPASS_EMAIL=test1@ritsubi.mail-box.ne.jp
NEXT_PUBLIC_STOREFRONT_AUTH_BYPASS_PASSWORD=DevCustomer123!

起動コマンド

apps/storefront/package.json に dev:bypass スクリプトを追加済みです。

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

VS Code タスク

apps/storefront/.vscode/tasks.json に「Dev: Storefront (Auth Bypass)」タスクを追加済みです。VS Code のコマンドパレットからタスクを実行すると、上記 pnpm run dev:bypass と同等の開発サーバーが立ち上がります。

注意事項

  1. 本番・ステージングでは無効化: NEXT_PUBLIC_STOREFRONT_AUTH_BYPASS は開発専用フラグです。本番ビルドや Cloudflare Workers デプロイ時には false のままにしてください。
  2. セキュリティ: デフォルトの資格情報は公開扱いのため、ネットワーク公開環境でバイパスを有効にしないでください。必要に応じて .env.local で値を上書きし、共有リポジトリにはコミットしないでください。
  3. シードアカウントの維持: 自動ログインは Vendure 上のユーザー情報に依存します。DB リセット後は必ず db:seed を実行し、必要に応じて pnpm seed:test-customers で SuperAdmin/テスト顧客を再投入してください。

参考

  • Storefront 認証設計: /docs/plans/email-login-implementation.plan.md
  • Vendure シード手順: /apps/vendure-server/src/seed-data.ts
  • Storefront 実装ガイド: /docs/03-implementation/frontend/index.md