Next.js WooCommerce 統合 (nextjs-woocommerce)
Next.js App Router アプリケーションと WPGraphQL、WooGraphQL、JWT 認証を介したヘッドレス WooCommerce バックエンドを連携させるための動作手順書兼チェックリストです。
前提条件とドキュメントリファレンス
- Next.js 14+ のプロジェクトが App Router と TypeScript で初期化されていること。
- アクティブな WooCommerce バックエンドに WPGraphQL、WooGraphQL、wp-graphql-jwt-authentication がインストールされていること。
- 完全な API スキーマと Next.js コードパターンについては、nextjs-woocommerce-reference.md を参照してください。
- 再利用可能なデータフェッチクライアントの実装については、woocommerce-fetcher.ts を参照してください。
段階的な実装チェックリスト
flowchart TD
S1["1. 環境設定とクライアント設定"] --> S2["2. 公開商品カタログ (ISR/SSG)"]
S2 --> S3["3. ユーザー認証 (JWT + Cookie)"]
S3 --> S4["4. 保護されたプロフィールと注文履歴"]
S4 --> S5["5. カートセッションとネイティブチェックアウトブリッジ"]
フェーズ 1: 環境設定とクライアント設定
- 環境変数の設定:
.env.exampleと.env.developmentにNEXT_PUBLIC_WORDPRESS_API_URL=https://your-store.com/graphqlを追加します。- チェックアウトリダイレクト用に
NEXT_PUBLIC_WORDPRESS_URL=https://your-store.comを追加します。
- ユニバーサルフェッチャーのセットアップ:
- ISR キャッシングと認証ヘッダーをサポートする woocommerce-fetcher.ts を実装します。
フェーズ 2: 公開商品カタログとタクソノミー
- カテゴリーナビゲーション: ヘッダーやカテゴリーメニュー用に
hideEmpty: trueを指定してproductCategoriesをクエリします。 - 商品一覧アーカイブ: ユニオンフラグメント (
... on SimpleProduct、... on VariableProduct) を使用してproductsをクエリします。next: { revalidate: 300, tags: ['products'] }を設定します。 - 商品詳細ページ: すべての商品スラッグをクエリする
generateStaticParams()を使用して、動的ルート (app/products/[slug]/page.tsx) を事前レンダリングします。
フェーズ 3: JWT 認証パイプライン
- ログインミューテーション:
login(input: { username, password })を実行するサーバーアクションを実装します。 - Cookie ストレージ: 返された
authTokenを安全なHttpOnlyCookie (auth_token) に保存します。 - セッションのバインド: 顧客から
sessionTokenが返される場合は、wc_sessionCookie に保存します。 - ログアウト: ユーザーログアウト時に認証 Cookie をクリアします。
フェーズ 4: 保護されたユーザーデータと注文
- 顧客プロフィール:
Authorization: Bearer <authToken>を渡してviewer { id name email }をクエリします。 - 注文履歴:
cache: 'no-store'を指定してcustomer { orders { nodes { id orderNumber total status } } }をクエリします。
フェーズ 5: カート管理とチェックアウト戦略
- カート状態:
addToCartミューテーションで返されるwoocommerce-sessionヘッダーを取得して永続化します。 - ネイティブチェックアウトブリッジ:
- ユーザーを
https://your-store.com/checkoutにリダイレクトし、ネイティブの WooCommerce 決済ゲートウェイ (ZarinPal、Mellat、Stripe)、地域の物流、コンプライアンスシールを、カスタムゲートウェイの書き換えなしで活用します。
- ユーザーを
エッジケースと既知の落とし穴
- 静的 vs 動的最適化の解除: ルートレイアウトや商品ページで Cookie を読み取ると、Next.js がフル SSR 動的モードに切り替わります。認証 Cookie は、サーバーアクション、ルートハンドラー、または独立したアカウントダッシュボードサブツリー (
app/account/...) でのみ読み取ってください。 - ポリモーフィックフラグメント:
products { nodes { price } }のような直接クエリは WooGraphQL で検証に失敗します。価格とバリエーションは常に... on SimpleProductと... on VariableProductでラップしてください。 - セッション損失: カートにアイテムを追加する際、
woocommerce-sessionヘッダーを再送信しないと、ミューテーションのたびに新しい空のカートが作成されます。 - GraphQL エンドポイントの CORS: WordPress が Next.js ドメインに対して
Access-Control-Allow-OriginとAccess-Control-Allow-Headers: Authorization, Content-Type, woocommerce-sessionヘッダーを送信するようにしてください。
検証とプリフライトテスト
-
pnpm buildが商品ページの静的生成で成功すること。 - ログインフォームが
auth_tokenを発行し、ダッシュボードにリダイレクトすることをテストする。 - アカウントページが有効なトークンで顧客詳細と注文リストをレンダリングすること。
- 複数のクライアントリクエストにわたって、「カートに追加」がカートのアイテム数を更新すること。