commercetools-storefront

commercetools ストアフロント（フレームワーク非依存）

commercetools ストアフロントの本番環境向けパターンです。共有 BFF 基盤から、B2C および B2B の各サーフェス固有の機能まで、幅広く扱います。ここで紹介するパターンはフレームワークに依存しません。それぞれを、意思決定と commercetools に即したコードの組み合わせとして示します。実装に必要なプリミティブ（ファイル構成、レンダリングやルーティングのプリミティブ、Cookie の読み書きのバインディング）は、フロントエンドのフレームワークが提供します。

アーキテクチャ上の前提 — サーバー層が存在します。 これらのパターンは、サーバーサイド層（SSR／サーバーコンポーネント／独立した BFF サービス）を備えたスタック上でストアフロントが稼働し、シークレットを保持して commercetools へのプロキシとして動作することを前提としています。以下の BFF およびシークレットに関するルールは必須であり、この前提に依存します。これらは SSR を第一に考えて設計されています。特定のフレームワークを使用する場合は、references/stack/ にあるそのスタックのアダプターを使用してください。たとえば、**Next.js スタック**は、ここで扱う各概念をそのフレームワークのプリミティブに対応付け、ファイル構成とレンダリングプリミティブの詳細をすべて担います。

リファレンス実装。 コード例にファイルパスやレンダリングプリミティブが示されている場合、リファレンス実装として Next.js App Router を使用しています。フレームワーク非依存のルールは常に周囲の説明に記載されており、アダプターが正確なプリミティブを指定します。

パスと状態に関する規約。

各リファレンス実装は、パスと状態管理に関する以下の規約に従います。これらの規約は技術的に必須ではありませんが、本番環境のストアフロントで広く使われており、コードベースの把握や新しい開発者のオンボーディングを容易にします。使用する正確なプリミティブについては、スタックアダプター内の concept-mapping.md を確認してください。

規約	意味
<server>/	サーバーサイドのコードルートです。実際のディレクトリは各スタックで指定します（Next.js の例：lib/）
<api>/	ブラウザーが呼び出してルーティングする、クライアント向けの API サーフェスです
<server>/ct/*	commercetools のヘルパーモジュールです
<server>/ct/client	apiRoot シングルトンです
<server>/types	アプリの型マッピングのルート（境界の型）です
<server>/mappers/	commercetools からアプリへのマッパーです
クライアント状態	フレームワークのクライアントサイドの状態管理／キャッシュ層です（具体的なライブラリはスタックによって異なります）。ユーザーごとに変更されるデータにはこれを使用してください

ワークフロー

このスキルが呼び出されたときは、必ず次の手順に従ってください。

1. ドキュメント検索（必須、最初に実行） — セッション中にこのスキルを初めて使用するときは、回答する前にこれを実行する必要があります。このスクリプトは、このスキルが対象とする製品に絞り込んだ、最新の検証済みドキュメントを収集し、主な根拠として提供します。このスキルを使用する際のドキュメント検索にはこのスクリプトを使用してください。それ以外の情報は Knowledge MCP が対象とします。スキルのテキストだけでなく、取得したドキュメントで詳細を必ず確認してください。

   node "<this skill's directory>/scripts/docs-search.mjs" \
     --query "<extract key terms from user's question>" \
     --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
     --model "<current-model>" \
     --commercetools-project-key "<if known>" \
     --commercetools-region "<if known>" \
     --limit 10
   

   commercetools のプロジェクトキーとリージョン（api.{region}.commercetools.com の形式）は、すでにコンテキストにある場合に限り渡してください。それ以外の場合は、どちらも省略してください。ファイルを検索したり、ユーザーに尋ねたりしてはいけません。

2. スキルのリファレンスとの統合 — 分析結果を ./references/ 内のローカルリファレンスと照合し、全体像を把握してください。

3. 実装ガイダンスの提供 — ドキュメントと、ユーザーが対象としている具体的な統合モードを統合してください。

オプションのスクリプト

GraphQL スキーマを取得 — commercetools の GraphQL クエリやミューテーションについてのコンテキストが必要なときに実行します。たとえば、クエリを作成する前にリソースのフィールド、型、利用可能なオペレーションを確認するときや、生成したばかりの GraphQL クエリ／ミューテーションを実際のスキーマと照合するときに使用します。単一の commercetools リソースについて、部分的な GraphQL SDL を取得します。

node scripts/graphql-schemata.mjs \
  --resource-name "<commercetools resource, e.g. Cart, Product, Order>" \
  --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
  --model "<current-model>"

出力は、そのリソースの GraphQL SDL です。リソース名が認識されない場合、スクリプトは有効なリソース名の一覧を出力します。正しい名前を選んで、再実行してください。注： SDL には スタブ型 が含まれる場合があります。これは、参照先のリソースをスタブとして表現したもので、コメントに実際の型名が記載されています。必要な型は、このスクリプトをその型名を --resource-name として再実行し、個別に取得してください。

OpenAPI（REST）スキーマを取得 — commercetools の REST エンドポイント、リクエスト／レスポンスのペイロード、または更新アクションについてのコンテキストが必要なときに実行します。たとえば、リクエストを組み立てる前にリソースの REST オペレーションを確認するときや、生成したばかりの REST リクエスト／ペイロードを実際の仕様と照合するときに使用します。単一の commercetools リソースについて、部分的な OpenAPI 仕様を取得します。

node scripts/openApi-schemata.mjs \
  --resource-name "<commercetools resource, e.g. api-Cart-write, api-Customer-read, checkout-Application>" \
  --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
  --model "<current-model>"

出力は、そのリソースの OpenAPI 仕様（YAML）です。REST リソースには、読み取りと書き込みを分けた命名形式（例：api-Cart-read、api-Cart-write）が使われます。リソース名が認識されない場合、スクリプトは有効なリソース名の一覧を出力します。正しい名前を選んで、再実行してください。注： 仕様には参照先の展開スキーマは含まれません。参照先リソースのスキーマは、そのリソースを --resource-name としてこのスクリプトを再実行し、個別に取得してください。

主なポイント

BFF パターンは必須です。 commercetools API の呼び出しはすべて、サーバーエンドポイント（BFF）を経由します。ブラウザーから commercetools を直接呼び出すことはありません。シークレットがクライアントバンドルに公開されることもありません（公開用の環境変数プレフィックスは使用しません）。（これにはサーバー層が必要です。上記のアーキテクチャ上の前提を参照してください。）

セッションはサーバーが管理します。 BFF がセッション状態を所有し、読み取りまたは書き込みを行う唯一の層です。保存方法はスタックの選択によります。HTTP 専用 Cookie に格納する署名付きトークン（ステートレス BFF）、または不透明な Cookie をキーとするサーバー側セッションストア（ステートフル BFF）が選べます。いずれの場合も、クライアントが保持するのは不透明な参照だけであり、セッションのシークレットや commercetools の認証情報そのものは保持しません。セッション署名用のシークレットは十分に強固なものとし、ハードコードしたりクライアントに公開したりしないでください。

カタログデータの読み込みにはサーバー側レンダリングを、変更可能なユーザー状態にはクライアント状態を使用します。 カタログ／不変データ（カテゴリページ、PDP）はサーバーで読み込み、<server>/ct/* を直接呼び出します。カート、アカウント、ユーザー固有のデータは、クライアント側の状態管理 → サーバーエンドポイント → commercetools SDK の順に読み込みます。

<server>/ct/* はサーバー専用です。 クライアントコンポーネントからインポートしないでください。型はアプリの型マッピングルート（<server>/types）からインポートしてください。

---

決定手順

以下の順序でストアフロントを構築します。各手順は、下記のリファレンスインデックスのセクションに対応しています。

1. スタックを選択します（存在する場合）。 フロントエンドに対応するアダプターを references/stack/<name>/ から選びます。アダプターが、ファイル構成、レンダリング／ルーティングのプリミティブ、セッションの仕組み、クライアント状態ライブラリ、デプロイを担います。
2. 共有基盤を実装します。 BFF の境界、セッション、commercetools クライアント、型の境界、カート、データ読み込みを接続します — references/core/。
3. オプションのコア機能を追加します。 必要に応じて、定期購入価格／注文などの横断的な追加機能を組み込みます — references/core/optional/。
4. B2C または B2B を選択します。 ドメイン機能とルールに応じた対応サーフェスを読み込みます — references/b2c/ または references/b2b/。
5. オプションのサーフェス機能を追加します。 サーフェス固有の追加機能を組み込みます。

---

リファレンスインデックス

スタック

フロントエンドのスタックに合ったアダプターを選択してください。references/stack/<name>/ 配下の各スタックフォルダーでは、このスキルのフレームワークに依存しないパターンを、そのスタックのプリミティブに適用します。また、ファイルレイアウト、レンダリングプリミティブ、デプロイを管理します。

スタック	リファレンス	コマンド
Next.js 16（App Router）+ next-intl v4 + Tailwind v4	stack/nextjs/overview.md	/nextjs-setup-project、/nextjs-deploy-vercel、/nextjs-deploy-netlify
Nuxt 4（Vue、SSR）+ Nitro + @nuxtjs/i18n v10 + nuxt-auth-utils + Pinia + Tailwind v4	stack/nuxtjs/overview.md	/nuxtjs-setup-project

共通基盤（references/core/）

タスク	リファレンス
新しいプロジェクトのスキャフォールディング（依存関係、スタイリング、ロケールルーティング、フォルダー構成）	フレームワーク固有です。アダプターの overview.md を参照してください
commercetools SDK シングルトン、サーバー管理セッション、BFF 境界	core/ct-client.md
共通の認証パターン：commercetools ログインエンドポイント、サーバーエンドポイントの構成、クライアント状態フック、ログアウト	core/customer-auth.md
新しい国／通貨／ロケールの追加 — COUNTRY_CONFIG のフラット構成	core/add-country.md
並列フェッチ、サーバーサイド TTL キャッシュ、クライアントキャッシュのハイドレーション、N+1 の回避	core/performance.md
商品画像 URL の変換（CDN、Imgix、Cloudinary）	core/image-config.md
カートの CRUD、カートの状態／コンテキスト、クライアント状態フック、ミニカートドロワー	core/cart.md
全文検索、ファセット設定、URL の状態、レンダラー	core/search-facets.md
新しい BFF エンドポイントとクライアント状態フックの追加（3 層パターン）	core/add-api.md
新しい単独ページまたは CMS 主導のページの追加	core/add-page.md
サーバーレンダリングとクライアントフェッチの判断、マッパー、BFF の構造、409 リトライ	core/data-loading.md
チェックアウトページのフロー、ステップルーティング、注文確定	core/checkout-page.md
PDP ルート、バリエーションセレクター、共通の商品詳細パターン	core/product-detail.md
ショッピングリスト（ウィッシュリスト、保存済みアイテム）	core/shopping-lists.md

コアのオプション機能（references/core/optional/）

タスク	リファレンス
継続課金価格 — マッパー、PDP のゲート、セレクターコンポーネント、recurrenceInfo を使用したカートへの追加	core/recurring-prices.md
継続注文 — スコープ設定、状態遷移、チェックアウト後の作成、継続ポリシー	core/recurring-orders.md
Vercel へのデプロイ	/deploy-vercel を実行します。commercetools の認証情報を確認した後、Vercel の公式エージェントスキルに引き継ぎます
Netlify へのデプロイ	/deploy-netlify を実行します。commercetools の認証情報を確認した後、Netlify の公式エージェントスキルに引き継ぎます

B2C ストアフロント（references/b2c/）

タスク	リファレンス
B2C の概要、重要なポイント、リファレンスの全インデックス	b2c/overview.md
カテゴリページ、商品マッパー、commercetools Search API、ProductCard/Grid	b2c/product-listing.md
B2C PDP ルート、画像ギャラリー、バリアントセレクター、AddToCartButton	b2c/product-detail.md
登録、ログイン、匿名カートのマージ、保護されたアカウントレイアウト	b2c/customer-auth.md
複数ステップのチェックアウト、配送方法、注文確定	b2c/checkout.md
ナビゲーションのパターン、ヘッダー、モバイルメニュー	b2c/navigation.md
共通 UI コンポーネントライブラリ	b2c/ui-components.md
PDP バリアントセレクターの設定（ブロックリスト、スウォッチ、並べ替え）	b2c/variant-config.md
ウィッシュリスト機能	b2c/wishlist.md

B2C オプション機能（references/b2c/optional/）

タスク	リファレンス
CSR なりすまし、デュアルセッション、ラインアイテム価格の上書き	b2c/optional/superuser.md
オンラインで購入して店舗で受け取り — チャネル API、店舗ごとの在庫	b2c/optional/bopis.md
商品バンドル — 親／子カートアイテム、連動更新	b2c/optional/bundles.md
商品割引、カート割引、割引コード、プロモーションバナー	b2c/optional/promotions.md
定期価格 — recurrencePrices[] 配列、ゲート	b2c/recurring-prices.md
定期注文 — 顧客スコープ、originOrder の展開、チェックアウト後の作成、skip/setSchedule	b2c/recurring-orders.md

B2B ストアフロント（references/b2b/）

タスク	リファレンス
B2B の概要、重要なポイント、リファレンスの全インデックス	b2b/overview.md
セッションフィールド、BU／ストアの選択、チャネルデータ、BusinessUnitContext	b2b/session-and-bu.md
ProductApi のセッションスコープ — ストア、チャネル、価格の注入、在庫状況	b2b/product-listing.md
B2B PDP ルート、バリアントセレクター、セッションスコープの価格設定	b2b/product-detail.md
as-associate によるカート CRUD、CartContext、BU＋ストアを使用した自動作成	b2b/cart.md
カートのチェックアウトと「見積もりを依頼」の送信、BU の住所、注文の確定	b2b/checkout.md
ログインエンドポイント、BU の自動選択、ログイン時に書き込まれるセッションフィールド	b2b/customer-auth.md
RBAC — すべての権限文字列、usePermissions、UI の表示制御パターン	b2b/permissions.md
見積もりダッシュボード — CT データモデル、BU ごとの統合スレッドリスト、ステータスラベル、クライアント状態フック	b2b/quotes.md
見積もりに関する購入者の操作 — 承認と注文確定、辞退、再交渉、状態ガード	b2b/quote-actions.md
承認ルール、承認フロー、述語ビルダー、ティアモデル	b2b/approval-workflows.md
ダッシュボードシェル、統計ウィジェット、ページ、サイドバーナビゲーション項目	b2b/dashboard.md
購入リスト（as-associate を介した commercetools ShoppingList、BU スコープ）	b2b/purchase-lists.md
新しい B2B BFF エンドポイントとクライアント状態フックの追加	b2b/add-api.md
B2B データの読み込み — サーバーレンダリングとクライアント取得、マッパー、BFF の形状	b2b/data-loading.md
B2B バリアントセレクターの設定	b2b/variant-config.md

B2B のオプション機能（references/b2b/optional/）

タスク	リファレンス
スーパーユーザーロール — すべてのストアのカートを表示、カートを切り替え	b2b/superuser.md
定期価格 — recurrencePrices[] 配列、as-associate によるカートへの追加、PDP の表示制御	b2b/recurring-prices.md
定期注文 — BU スコープ、カートの展開、カートからの作成、複製、ダッシュボード	b2b/recurring-orders.md

---

優先度

重大

• BFF アーキテクチャ — <server>/ct/* はサーバー専用です。クライアントコンポーネントで commercetools SDK をインポートすることは一切できません。（サーバーティアが必要です — アーキテクチャの前提を参照してください。）
• セッションとクライアントシークレット — commercetools のクライアントシークレットとセッション署名に使用するシークレットは、サーバー専用の環境変数です。ハードコードしたり、クライアントバンドルに公開したりしないでください（public の環境変数プレフィックスは使用しません）。
• commercetools のログインエンドポイント — apiRoot.login().post() を使用し、apiRoot.customers().login() は使用しないでください。
• B2B：as-associate チェーン — B2B の書き込み（カート、注文、見積もり、承認、BU）はすべて apiRoot.asAssociate().* を介してください。ユーザー向けの B2B ミューテーションに、プロジェクトレベルの apiRoot.* は使用しないでください。
• B2B：セッションの B2B フィールド — businessUnitKey + storeKey + distributionChannelId + supplyChannelId + productSelectionId は、常に getStoreChannelData(storeKey) からまとめて書き込んでください。
• B2B：ロケールの3フィールドの原子性 — locale、currency、country はすべてまとめて更新する必要があります。ロケールまたは通貨が変わった場合は、cartId をリセットしてください。

フレームワークのバージョンによる制約については、使用するスタックの overview.md を参照してください。

HIGH

• 並列フェッチ — サーバー側レンダリングのロードで、依存しないフェッチには Promise.all を使用します。リクエストのウォーターフォールを発生させません。
• 型安全性 — フロントエンドのコンポーネントでは、アプリの型マッピングルート（<server>/types）から型をインポートし、<server>/ct/* からはインポートしません。
• commercetools の型境界 — commercetools SDK のレスポンスが <server>/ct/ の外に出る前に、<server>/mappers/ でアプリの型にマッピングします。
• クライアント状態の無効化 — ログイン、ログアウト、注文の確定後に、該当するクライアント状態を無効化または更新します。
• B2B：クライアントの状態マネージャー／キャッシュキーに BU キーを含める — ダッシュボードの状態はすべて businessUnitKey をキーにします（例：[KEY, businessUnitKey] タプル）。これにより BU の切り替え時に状態が更新されます。

MEDIUM

• Product Search API — apiRoot.products().search() を使用し、非推奨の productProjections().search() は使用しません。commercetools-platform スキル → product-search.md を参照してください。
• サーバー側 TTL キャッシュ — 変更頻度の低い commercetools データは、フレームワークの TTL 付きサーバー側キャッシュでラップします。ユーザーごと、またはセッションごとのデータには絶対に使用しないでください。（Next.js：unstable_cache — アダプターを参照してください。）

---

アンチパターン早見表

アンチパターン	正しい方法
クライアントコンポーネントで <server>/ct/client（apiRoot）をインポートする	クライアント状態フック → サーバーエンドポイント → <server>/ct/ を使用します
コンポーネント内でエンドポイント（fetch('/<api>/*')）を直接呼び出す	クライアントのデータ／状態モジュールにカプセル化します
ページまたはサーバーエンドポイント内で new ClientBuilder() を使用する	<server>/ct/client にシングルトンの apiRoot を配置します
commercetools REST エンドポイントに fetch() を直接使用する	常に apiRoot を使用します — SDK が OAuth トークンと更新を管理します
commercetools のシークレットをクライアントバンドルに公開する（公開環境変数プレフィックス）	サーバー専用の環境変数を使用し、公開プレフィックスは付けません
product.name['en-US']（ロケールキーのハードコード）	getLocalizedString(product.name, locale) を使用します
(centAmount / 100).toFixed(2)	formatMoney(centAmount, currencyCode, locale) を使用します
依存しないフェッチに対して await を順番に使用する	Promise.all([fetchA(), fetchB()]) を使用します
apiRoot.customers().login()	apiRoot.login().post() を使用します
コンポーネントで commercetools SDK の型を使用する	<server>/types の型を使用し、<server>/mappers/ でマッピングします
B2B：ログイン済みユーザーに apiRoot.carts().post(...) を使用する	asAssociate().withAssociateIdValue(...).inBusinessUnitKey(...).carts().post(...) を使用します
B2B：BU にスコープされたクライアント状態を BU キーで指定しない	状態エントリーを businessUnitKey でキー設定します（例：[KEY_ORDERS, businessUnitKey]）
B2B：ラウンドごとの表示に StagedQuote.sellerComment を使用する	見積もりの作成時点のスナップショットである Quote.sellerComment を使用します
B2B：購入リストに apiRoot.shoppingLists() を使用する	BU にスコープされ、権限が適用される asAssociate().*.shoppingLists() を使用します