From medusa-dev
Guides Medusa storefronts: JS SDK for API calls, React Query for data fetching/mutations, custom routes, error handling, cache invalidation.
npx claudepluginhub adaptive-machines/medusa-agent-skills --plugin medusa-devThis skill uses the workspace's default tool permissions.
Frontend integration guide for building storefronts with Medusa. Covers SDK usage, React Query patterns, and calling custom API routes.
Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.
Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
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 stringssdk-locate-first - Always locate where SDK is instantiated in the project before using itquery-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, isError 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.