building-storefronts by medusajs/medusa-agent-skills
npx skills add https://github.com/medusajs/medusa-agent-skills --skill building-storefronts使用 Medusa 构建前端商店的集成指南。涵盖 SDK 使用、React Query 模式以及调用自定义 API 路由。
进行任何前端开发任务时,请加载此技能,包括:
同时,在以下情况加载 building-with-medusa 技能: 构建前端调用的后端 API 路由时
下面的快速参考不足以用于实现。 在编写前端集成代码之前,你必须加载参考文件。
实现前端功能时加载此参考:
references/frontend-integration.mdreferences/frontend-integration.mdreferences/frontend-integration.md广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
| 优先级 | 类别 | 影响 | 前缀 |
|---|
| 1 | SDK 使用 | 关键 | sdk- |
| 2 | React Query 模式 | 高 | query- |
| 3 | 数据显示 | 高(包含关键的价格规则) | display- |
| 4 | 错误处理 | 中 | error- |
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 - 切勿在请求体上使用 JSON.stringify() - SDK 会自动处理序列化sdk-plain-objects - 向请求体传递普通的 JavaScript 对象,而不是字符串sdk-locate-first - 使用 SDK 前,务必先在项目中定位 SDK 的实例化位置query-use-query - 使用 useQuery 处理 GET 请求(数据获取)query-use-mutation - 使用 useMutation 处理 POST/DELETE 请求(变更操作)query-invalidate - 在 onSuccess 中使查询失效,以便在变更操作后刷新数据query-keys-hierarchical - 以分层结构组织查询键,以实现有效的缓存管理query-loading-states - 始终处理 isLoading、isPending、isError 状态display-price-format - 关键:从 Medusa 获取的价格按原样存储($49.99 = 49.99,不是以分为单位)。直接显示它们 - 切勿除以 100error-on-error - 在变更操作中实现 onError 回调以处理失败error-display - 当变更操作失败时向用户显示错误信息error-rollback - 使用乐观更新并在出错时回滚,以获得更好的用户体验始终向 SDK 传递普通对象 - 切勿使用 JSON.stringify():
// ✅ 正确 - 普通对象
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 使用:
React Query:
数据显示:
错误处理:
有关详细的模式和示例,请加载参考文件:
references/frontend-integration.md - SDK 使用、React Query 模式、API 集成
参考文件包含:
将此技能用于(主要来源):
将 MedusaDocs MCP 服务器用于(次要来源):
为什么技能优先:
⚠️ 关键:始终使用 Medusa JS SDK - 切勿使用常规 fetch()
当构建跨越后端和前端的特性时:
sdk.store.product.list())sdk.client.fetch("/store/my-route")为什么需要 SDK:
x-publishable-api-key 请求头Authorization 和会话请求头有关后端 API 路由模式,请参阅 building-with-medusa。
每周安装次数
839
代码仓库
GitHub 星标数
115
首次出现
2026年1月26日
安全审计
安装于
codex734
github-copilot731
gemini-cli725
opencode721
kimi-cli681
amp681
Frontend integration guide for building storefronts with Medusa. Covers SDK usage, React Query patterns, and calling custom API routes.
Load this skill for ANY storefront development task, including:
Also load building-with-medusa when: Building the backend API routes that the storefront calls
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:
references/frontend-integration.md firstreferences/frontend-integration.md firstreferences/frontend-integration.md first| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | SDK Usage | CRITICAL | sdk- |
| 2 | React Query Patterns | HIGH | query- |
| 3 | Data Display | HIGH (includes CRITICAL price rule) | display- |
| 4 | Error Handling | MEDIUM | error- |
sdk-always-use - ALWAYS use the Medusa JS SDK for ALL API requests - NEVER use regular fetch()sdk-existing-methods - For built-in endpoints, use existing SDK methods (sdk.store.product.list(), sdk.admin.order.retrieve())sdk-client-fetch - For custom API routes, use sdk.client.fetch()sdk-required-headers - SDK automatically adds required headers (publishable API key for store, auth for admin) - regular fetch() missing these headers causes errorssdk-no-json-stringify - NEVER use JSON.stringify() on body - SDK handles serialization automaticallysdk-plain-objects - Pass plain JavaScript objects to body, not stringsquery-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 mutationsquery-keys-hierarchical - Structure query keys hierarchically for effective cache managementquery-loading-states - Always handle isLoading, isPending, statesdisplay-price-format - CRITICAL : Prices from Medusa are stored as-is ($49.99 = 49.99, NOT in cents). Display them directly - NEVER divide by 100error-on-error - Implement onError callback in mutations to handle failureserror-display - Show error messages to users when mutations failerror-rollback - Use optimistic updates with rollback on error for better UXALWAYS pass plain objects to the SDK - NEVER use 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,
})
})
Why this matters:
Before implementing, verify you're NOT doing these:
SDK Usage:
React Query:
Data Display:
Error Handling:
For detailed patterns and examples, load reference file:
references/frontend-integration.md - SDK usage, React Query patterns, API integration
The reference file contains:
Use this skill for (PRIMARY SOURCE):
Use MedusaDocs MCP server for (SECONDARY SOURCE):
Why skills come first:
⚠️ CRITICAL: ALWAYS use the Medusa JS SDK - NEVER use regular fetch()
When building features that span backend and frontend:
sdk.store.product.list())sdk.client.fetch("/store/my-route")Why the SDK is required:
x-publishable-api-key headerAuthorization and session headersSee building-with-medusa for backend API route patterns.
Weekly Installs
839
Repository
GitHub Stars
115
First Seen
Jan 26, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
codex734
github-copilot731
gemini-cli725
opencode721
kimi-cli681
amp681
React 组合模式指南:Vercel 组件架构最佳实践,提升代码可维护性
102,200 周安装
创始人销售指南:16位专家见解,助你建立可复制的早期销售流程 | Founder-Sales
827 周安装
.NET 10 与 C# 14 最佳实践指南:最小化 API、安全与架构
828 周安装
faster-whisper:本地语音转文本工具,速度提升4-6倍,支持多语言转录与字幕生成
828 周安装
Vite 8 前端构建工具:Rolldown 驱动,快速开发与生产优化
829 周安装
MS OneDrive API 集成指南:使用 Membrane CLI 实现文件上传、共享与管理
830 周安装
学术写作与研究方法论指南:研究设计、文献综述、引文管理与论文结构
831 周安装
sdk-locate-first - Always locate where SDK is instantiated in the project before using itisError