building-storefronts
SDK-first frontend integration for Medusa storefronts with React Query patterns and critical API calling rules.
- Always use the Medusa JS SDK for all API requests—never use regular fetch(), as it lacks required headers (publishable API key for store routes, auth for admin routes)
- Pass plain JavaScript objects to SDK methods; never use JSON.stringify() on body parameters, as the SDK handles serialization automatically
- Use useQuery for GET requests and useMutation for POST/DELETE requests, invalidating queries in onSuccess callbacks to refresh data after mutations
- Prices from Medusa are stored as-is ($49.99 = 49.99, not in cents)—display them directly without dividing by 100
- Load the reference file (references/frontend-integration.md) before implementing storefront features for complete SDK patterns, React Query examples, and error handling strategies
Medusa Storefront Development
Frontend integration guide for building storefronts with Medusa. Covers SDK usage, React Query patterns, and calling custom API routes.
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
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.
More from medusajs/medusa-agent-skills
building-with-medusa
Load automatically when planning, researching, or implementing ANY Medusa backend features (custom modules, API routes, workflows, data models, module links, business logic). REQUIRED for all Medusa backend work in ALL modes (planning, implementation, exploration). Contains architectural patterns, best practices, and critical rules that MCP servers don't provide.
1.8Kbuilding-admin-dashboard-customizations
Load automatically when planning, researching, or implementing Medusa Admin dashboard UI (widgets, custom pages, forms, tables, data loading, navigation). REQUIRED for all admin UI work in ALL modes (planning, implementation, exploration). Contains design patterns, component usage, and data loading patterns that MCP servers don't provide.
1.8Kstorefront-best-practices
ALWAYS use this skill when working on ecommerce storefronts, online stores, shopping sites. Use for ANY storefront component including checkout pages, cart, payment flows, product pages, product listings, navigation, homepage, or ANY page/component in a storefront. CRITICAL for adding checkout, implementing cart, integrating Medusa backend, or building any ecommerce functionality. Framework-agnostic (Next.js, SvelteKit, TanStack Start, React, Vue). Provides patterns, decision frameworks, backend integration guidance.
1.7Klearning-medusa
Load automatically when user asks to learn Medusa development (e.g., "teach me how to build with medusa", "guide me through medusa", "I want to learn medusa"). Interactive guided tutorial where Claude acts as a coding bootcamp instructor, teaching step-by-step with checkpoints and verification.
1.3Kdb-migrate
Run database migrations in Medusa
1.1Kdb-generate
Generate database migrations for a Medusa module
1.1K