Back to Details

building-storefronts

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Medusa Storefront Development

Medusa 店面开发

Frontend integration guide for building storefronts with Medusa. Covers SDK usage, React Query patterns, and calling custom API routes.
使用Medusa构建店面的前端集成指南。涵盖SDK使用、React Query模式以及自定义API路由调用。

When to Apply

适用场景

Load this skill for ANY storefront development task, including:
  • Calling custom Medusa API routes from the storefront
  • Integrating Medusa SDK in frontend applications
  • Using React Query for data fetching
  • Implementing mutations with optimistic updates
  • Error handling and cache invalidation
Also load building-with-medusa when: Building the backend API routes that the storefront calls
任何店面开发任务都需加载此技能，包括：
  • 从店面调用自定义Medusa API路由
  • 在前端应用中集成Medusa SDK
  • 使用React Query进行数据获取
  • 实现带乐观更新的突变操作
  • 错误处理与缓存失效
同时，当构建店面调用的后端API路由时，请加载building-with-medusa技能

CRITICAL: Load Reference Files When Needed

重要提示：必要时加载参考文件

The quick reference below is NOT sufficient for implementation. You MUST load the reference file before writing storefront integration code.
Load this reference when implementing storefront features:
  • Calling API routes? → MUST load 
    references/frontend-integration.md
    first
  • Using SDK? → MUST load 
    references/frontend-integration.md
    first
  • Implementing React Query? → MUST load 
    references/frontend-integration.md
    first
以下快速参考内容不足以支撑实现工作。在编写店面集成代码前，必须加载参考文件。
实现店面功能时，请加载以下参考文件：
  • 调用API路由？ → 必须先加载
    references/frontend-integration.md
  • 使用SDK？ → 必须先加载
    references/frontend-integration.md
  • 实现React Query？ → 必须先加载
    references/frontend-integration.md

Rule Categories by Priority

按优先级划分的规则类别

PriorityCategoryImpactPrefix
1SDK UsageCRITICAL
sdk-
2React Query PatternsHIGH
query-
3Data DisplayHIGH (includes CRITICAL price rule)
display-
4Error HandlingMEDIUM
error-
优先级类别影响程度前缀
1SDK使用关键
sdk-
2React Query模式高
query-
3数据展示高（包含关键价格规则）
display-
4错误处理中
error-

Quick Reference

快速参考

1. SDK Usage (CRITICAL)

1. SDK使用（关键）

  • sdk-no-json-stringify
    - NEVER use JSON.stringify() on body - SDK handles serialization automatically
  • sdk-plain-objects
    - Pass plain JavaScript objects to body, not strings
  • sdk-locate-first
    - Always locate where SDK is instantiated in the project before using it
  • sdk-client-fetch
    - Use 
    sdk.client.fetch()
    for custom API routes
  • sdk-auto-headers
    - SDK automatically adds Content-Type, auth headers, and API key
  • sdk-no-json-stringify
    - 绝对不要在请求体上使用JSON.stringify() - SDK会自动处理序列化
  • sdk-plain-objects
    - 向请求体传入普通JavaScript对象，而非字符串
  • sdk-locate-first
    - 使用SDK前，务必先定位项目中SDK的实例化位置
  • sdk-client-fetch
    - 对自定义API路由使用
    sdk.client.fetch()
  • sdk-auto-headers
    - SDK会自动添加Content-Type、认证头以及API密钥

2. React Query Patterns (HIGH)

2. React Query模式（高）

  • query-use-query
    - Use 
    useQuery
    for GET requests (data fetching)
  • query-use-mutation
    - Use 
    useMutation
    for POST/DELETE requests (mutations)
  • query-invalidate
    - Invalidate queries in 
    onSuccess
    to refresh data after mutations
  • query-keys-hierarchical
    - Structure query keys hierarchically for effective cache management
  • query-loading-states
    - Always handle 
    isLoading
    , 
    isPending
    , 
    isError
    states
  • query-use-query
    - 对GET请求（数据获取）使用
    useQuery
  • query-use-mutation
    - 对POST/DELETE请求（突变操作）使用
    useMutation
  • query-invalidate
    - 在
    onSuccess
    中使查询失效，以便在突变后刷新数据
  • query-keys-hierarchical
    - 按层级结构组织查询键，实现高效缓存管理
  • query-loading-states
    - 务必处理
    isLoading
    、
    isPending
    、
    isError
    状态

3. Data Display (HIGH)

3. 数据展示（高）

  • display-price-format
    - CRITICAL: Prices from Medusa are stored as-is ($49.99 = 49.99, NOT in cents). Display them directly - NEVER divide by 100
  • display-price-format
    - 关键：Medusa中的价格按原始值存储（$49.99 = 49.99，而非以美分为单位）。直接展示即可——绝对不要除以100

4. Error Handling (MEDIUM)

4. 错误处理（中）

  • error-on-error
    - Implement 
    onError
    callback in mutations to handle failures
  • error-display
    - Show error messages to users when mutations fail
  • error-rollback
    - Use optimistic updates with rollback on error for better UX
  • error-on-error
    - 在突变操作中实现
    onError
    回调以处理失败情况
  • error-display
    - 突变失败时向用户展示错误信息
  • error-rollback
    - 结合乐观更新与错误回滚，提升用户体验

Critical SDK Pattern

关键SDK模式

ALWAYS pass plain objects to the SDK - NEVER use JSON.stringify():
typescript
// ✅ 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,
  })
})
Why this matters:
  • The SDK handles JSON serialization automatically
  • Using JSON.stringify() will double-serialize and break the request
  • The server won't be able to parse the body
务必向SDK传入普通对象——绝对不要使用JSON.stringify():
typescript
// ✅ 正确 - 普通对象
await sdk.client.fetch("/store/reviews", {
  method: "POST",
  body: {
    product_id: "prod_123",
    rating: 5,
  }
})

// ❌ 错误 - JSON.stringify会破坏请求
await sdk.client.fetch("/store/reviews", {
  method: "POST",
  body: JSON.stringify({  // ❌ 不要这样做！
    product_id: "prod_123",
    rating: 5,
  })
})
为什么这很重要：
  • SDK会自动处理JSON序列化
  • 使用JSON.stringify()会导致双重序列化，破坏请求
  • 服务器将无法解析请求体

Common Mistakes Checklist

常见错误检查清单

Before implementing, verify you're NOT doing these:
SDK Usage:
  • Using JSON.stringify() on the body parameter
  • Manually setting Content-Type headers (SDK adds them)
  • Hardcoding SDK import paths (locate in project first)
  • Not using sdk.client.fetch() for custom routes
React Query:
  • Not invalidating queries after mutations
  • Using flat query keys instead of hierarchical
  • Not handling loading and error states
  • Forgetting to disable buttons during mutations (isPending)
Data Display:
  • CRITICAL: Dividing prices by 100 when displaying (prices are stored as-is: $49.99 = 49.99, NOT in cents)
Error Handling:
  • Not implementing onError callbacks
  • Not showing error messages to users
  • Not handling network failures gracefully
实现前，请确认你没有以下操作：
SDK使用：
  • 在body参数上使用JSON.stringify()
  • 手动设置Content-Type请求头（SDK会自动添加）
  • 硬编码SDK导入路径（先在项目中定位）
  • 对自定义路由不使用sdk.client.fetch()
React Query：
  • 突变后不使查询失效
  • 使用扁平查询键而非层级结构
  • 不处理加载和错误状态
  • 突变期间忘记禁用按钮（isPending状态）
数据展示：
  • 关键错误：展示价格时除以100（价格按原始值存储：$49.99 = 49.99，而非以美分为单位）
错误处理：
  • 未实现onError回调
  • 不向用户展示错误信息
  • 未优雅处理网络故障

How to Use

使用方法

For detailed patterns and examples, load reference file:
references/frontend-integration.md - SDK usage, React Query patterns, API integration
The reference file contains:
  • Step-by-step SDK integration patterns
  • Complete React Query examples
  • Correct vs incorrect code examples
  • Query key best practices
  • Optimistic update patterns
  • Error handling strategies
如需详细模式与示例，请加载参考文件：
references/frontend-integration.md - SDK使用、React Query模式、API集成
参考文件包含：
  • 分步SDK集成模式
  • 完整的React Query示例
  • 正确与错误的代码示例
  • 查询键最佳实践
  • 乐观更新模式
  • 错误处理策略

When to Use MedusaDocs MCP Server

何时使用MedusaDocs MCP Server

Use this skill for (PRIMARY SOURCE):
  • How to call custom API routes from storefront
  • SDK usage patterns (sdk.client.fetch)
  • React Query integration patterns
  • Common mistakes and anti-patterns
Use MedusaDocs MCP server for (SECONDARY SOURCE):
  • Built-in SDK methods (sdk.admin., sdk.store.)
  • Official Medusa SDK API reference
  • Framework-specific configuration options
Why skills come first:
  • Skills contain critical patterns like "don't use JSON.stringify" that MCP doesn't emphasize
  • Skills show correct vs incorrect patterns; MCP shows what's possible
  • Planning requires understanding patterns, not just API reference
此技能适用于（主要来源）：
  • 如何从店面调用自定义API路由
  • SDK使用模式（sdk.client.fetch）
  • React Query集成模式
  • 常见错误与反模式
MedusaDocs MCP Server适用于（次要来源）：
  • 内置SDK方法（sdk.admin., sdk.store.）
  • 官方Medusa SDK API参考
  • 框架特定配置选项
为什么优先使用技能：
  • 技能包含像“不要使用JSON.stringify”这样的关键模式，而MCP并未强调这些
  • 技能展示正确与错误的模式；MCP展示可用功能
  • 规划工作需要理解模式，而非仅依赖API参考

Integration with Backend

与后端的集成

When building features that span backend and frontend:
  1. Backend (building-with-medusa skill): Module → Workflow → API Route
  2. Storefront (this skill): SDK → React Query → UI Components
  3. Connection: Storefront calls backend API routes via 
    sdk.client.fetch()
See 
building-with-medusa
for backend API route patterns.
当构建跨后端与前端的功能时：
  1. 后端（building-with-medusa技能）： 模块 → 工作流 → API路由
  2. 店面（本技能）： SDK → React Query → UI组件
  3. 连接方式： 店面通过
    sdk.client.fetch()
    调用后端API路由
有关后端API路由模式，请查看
building-with-medusa
技能。