building-storefronts

Medusa ストアフロント開発

Medusa を使用してストアフロントを構築するためのフロントエンド統合ガイドです。SDK の使用方法、React Query のパターン、カスタム API ルートの呼び出しについて説明します。

適用する場合

次のいずれかのストアフロント開発タスクでは、このスキルを読み込んでください。

• ストアフロントからカスタム Medusa API ルートを呼び出す
• フロントエンドアプリケーションに Medusa SDK を統合する
• データ取得に React Query を使用する
• 楽観的更新を使用してミューテーションを実装する
• エラー処理とキャッシュ無効化を行う

次の場合は building-with-medusa も読み込んでください。：ストアフロントから呼び出すバックエンド API ルートを構築する場合

重要：必要に応じてリファレンスファイルを読み込む

以下のクイックリファレンスだけでは、実装には不十分です。 ストアフロント統合コードを書く前に、必ずリファレンスファイルを読み込んでください。

ストアフロント機能を実装するときは、このリファレンスを読み込んでください。

• API ルートを呼び出す場合 → まず references/frontend-integration.md を必ず読み込んでください
• SDK を使用する場合 → まず references/frontend-integration.md を必ず読み込んでください
• React Query を実装する場合 → まず references/frontend-integration.md を必ず読み込んでください

優先度別ルールカテゴリ

優先度	カテゴリ	影響	プレフィックス
1	SDK の使用	重大	sdk-
2	React Query のパターン	高	query-
3	データ表示	高（重大な価格ルールを含む）	display-
4	エラー処理	中	error-

クイックリファレンス

1. SDK の使用（重大）

• sdk-always-use - すべての API リクエストでは、必ず Medusa JS SDK を使用してください - 通常の fetch() は絶対に使用しないでください
• sdk-existing-methods - 組み込みエンドポイントには、既存の SDK メソッド（sdk.store.product.list()、sdk.admin.order.retrieve()）を使用してください
• sdk-client-fetch - カスタム API ルートには、sdk.client.fetch() を使用してください
• sdk-required-headers - SDK は必要なヘッダー（ストア用の公開 API キー、管理者用の認証情報）を自動的に追加します - 通常の fetch() ではこれらのヘッダーが不足するため、エラーが発生します
• sdk-no-json-stringify - body に JSON.stringify() を絶対に使用しないでください - SDK が自動的にシリアル化します
• sdk-plain-objects - body には文字列ではなく、プレーンな JavaScript オブジェクトを渡してください
• sdk-locate-first - SDK を使用する前に、必ずプロジェクト内で SDK のインスタンス化箇所を確認してください

2. React Query のパターン（高）

• query-use-query - GET リクエスト（データ取得）には useQuery を使用してください
• query-use-mutation - POST/DELETE リクエスト（ミューテーション）には useMutation を使用してください
• query-invalidate - ミューテーション後にデータを更新するため、onSuccess でクエリを無効化してください
• query-keys-hierarchical - 効果的なキャッシュ管理のため、クエリキーを階層的に構成してください
• query-loading-states - isLoading、isPending、isError の状態を必ず処理してください

3. データ表示（高）

• display-price-format - 重大：Medusa の価格はそのまま保存されます（$49.99 = 49.99 であり、セント単位ではありません）。そのまま表示してください - 100 で割らないでください

4. エラー処理（中）

• error-on-error - 失敗に対処するため、ミューテーションに onError コールバックを実装してください
• error-display - ミューテーションが失敗したときは、ユーザーにエラーメッセージを表示してください
• error-rollback - UX を向上させるため、エラー時のロールバックを伴う楽観的更新を使用してください

重要な SDK のパターン

プレーンなオブジェクトを必ず SDK に渡してください - JSON.stringify() は絶対に使用しないでください。

// ✅ CORRECT - Plain object
await sdk.client.fetch("/store/reviews", {
  method: "POST",
  body: {
    product_id: "prod_123",
    rating: 5,
  }
})

// ❌ WRONG - JSON.stringify breaks the request
await sdk.client.fetch("/store/reviews", {
  method: "POST",
  body: JSON.stringify({  // ❌ DON'T DO THIS!
    product_id: "prod_123",
    rating: 5,
  })
})

重要な理由：

• SDK が JSON のシリアル化を自動的に処理します
• JSON.stringify() を使用すると二重にシリアル化され、リクエストが壊れます
• サーバーが body を解析できなくなります

よくある間違いのチェックリスト

実装を始める前に、次のことをしていないか確認してください。

SDK の使用：

• Medusa JS SDK ではなく通常の fetch() を使用している（ヘッダー不足のエラーが発生します）
• 組み込みエンドポイントに既存の SDK メソッドを使用していない（例：sdk.store.product.list() ではなく sdk.client.fetch("/store/products") を使用している）
• body パラメーターに JSON.stringify() を使用している
• Content-Type ヘッダーを手動で設定している（SDK が追加します）
• SDK のインポートパスをハードコードしている（まずプロジェクト内で確認してください）
• カスタムルートに sdk.client.fetch() を使用していない

React Query：

• ミューテーション後にクエリを無効化していない
• 階層型ではなくフラットなクエリキーを使用している
• 読み込み状態とエラー状態を処理していない
• ミューテーション中（isPending）にボタンを無効化し忘れている

データ表示：

• 重大： 表示時に価格を 100 で割っている（価格はそのまま保存されます。$49.99 は 49.99 であり、セント単位ではありません）

エラー処理：

• onError コールバックを実装していない
• エラーメッセージをユーザーに表示していない
• ネットワーク障害を適切に処理していない

使用方法

詳しいパターンや例については、参照ファイルを読み込んでください。

references/frontend-integration.md - SDK usage, React Query patterns, API integration

参照ファイルには、次の内容が含まれています。

• SDK 統合の手順を段階的に説明したパターン
• React Query の完全な例
• 正しいコード例と誤ったコード例
• クエリキーのベストプラクティス
• 楽観的更新のパターン
• エラー処理の方法

MedusaDocs MCP Server を使用するタイミング

次の用途では、このスキルを使用してください（主な情報源）。

• ストアフロントからカスタム API ルートを呼び出す方法
• SDK の使用パターン（sdk.client.fetch）
• React Query の統合パターン
• よくある間違いとアンチパターン

次の用途では、MedusaDocs MCP server を使用してください（補助的な情報源）。

• 組み込み SDK メソッド（sdk.admin., sdk.store.）
• Medusa SDK の公式 API リファレンス
• フレームワーク固有の設定オプション

スキルを先に使う理由：

• スキルには、MCP であまり強調されていない「JSON.stringify を使わない」といった重要なパターンが含まれています
• スキルでは正しいパターンと誤ったパターンを示しますが、MCP では可能なことを示します
• 計画には、API リファレンスだけでなくパターンの理解が必要です

バックエンドとの統合

⚠️ 重大：必ず Medusa JS SDK を使用してください。通常の fetch() は絶対に使用しないでください。

バックエンドとフロントエンドにまたがる機能を構築する場合：

1. バックエンド（building-with-medusa スキル）： モジュール → ワークフロー → API ルート
2. ストアフロント（このスキル）： SDK → React Query → UI コンポーネント
3. 接続：
   • 組み込みエンドポイント：既存の SDK メソッドを使用します（sdk.store.product.list()）
   • カスタム API ルート：sdk.client.fetch("/store/my-route") を使用します
   • 通常の fetch() は絶対に使用しないでください。 パブリッシャブル API キーがないとエラーになります

SDK が必要な理由：

• ストアルートには x-publishable-api-key ヘッダーが必要です
• 管理者ルートには Authorization ヘッダーとセッションヘッダーが必要です
• SDK は必要なすべてのヘッダーを自動的に処理します
• ヘッダーなしで通常の fetch() を使用すると、認証／認可エラーが発生します

バックエンドの API ルートパターンについては、building-with-medusa を参照してください。