[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill-medusa-building-storefronts":3,"mdc--9un7b9-key":43,"related-repo-medusa-building-storefronts":1633,"related-org-medusa-building-storefronts":1720},{"slug":4,"name":4,"fn":5,"description":6,"org":7,"tags":12,"stars":27,"repoUrl":28,"updatedAt":29,"license":30,"forks":31,"topics":32,"repo":38,"sourceUrl":41,"mdContent":42},"building-storefronts","implement Medusa storefront features","Load automatically when planning, researching, or implementing Medusa storefront features (calling custom API routes, SDK integration, React Query patterns, data fetching). REQUIRED for all storefront development in ALL modes (planning, implementation, exploration). Contains SDK usage patterns, frontend integration, and critical rules for calling Medusa APIs.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},"medusa","Medusa","https:\u002F\u002Fpexgzepcugksgbtrxkhf.supabase.co\u002Fstorage\u002Fv1\u002Fobject\u002Fpublic\u002Forg-logos\u002Fmedusa.jpg","medusajs",[13,17,18,21,24],{"name":14,"slug":15,"type":16},"React","react","tag",{"name":9,"slug":8,"type":16},{"name":19,"slug":20,"type":16},"E-commerce","e-commerce",{"name":22,"slug":23,"type":16},"Engineering","engineering",{"name":25,"slug":26,"type":16},"Frontend","frontend",197,"https:\u002F\u002Fgithub.com\u002Fmedusajs\u002Fmedusa-agent-skills","2026-04-06T18:29:55.957429",null,24,[33,34,35,36,37,8],"agentic-commerce","claude","claude-code","commerce","ecommerce",{"repoUrl":28,"stars":27,"forks":31,"topics":39,"description":40},[33,34,35,36,37,8],"Agent skills and commands for Medusa best practices and conventions.","https:\u002F\u002Fgithub.com\u002Fmedusajs\u002Fmedusa-agent-skills\u002Ftree\u002FHEAD\u002Fplugins\u002Fmedusa-dev\u002Fskills\u002Fbuilding-storefronts","---\nname: building-storefronts\ndescription: Load automatically when planning, researching, or implementing Medusa storefront features (calling custom API routes, SDK integration, React Query patterns, data fetching). REQUIRED for all storefront development in ALL modes (planning, implementation, exploration). Contains SDK usage patterns, frontend integration, and critical rules for calling Medusa APIs.\n---\n\n# Medusa Storefront Development\n\nFrontend integration guide for building storefronts with Medusa. Covers SDK usage, React Query patterns, and calling custom API routes.\n\n## When to Apply\n\n**Load this skill for ANY storefront development task, including:**\n- Calling custom Medusa API routes from the storefront\n- Integrating Medusa SDK in frontend applications\n- Using React Query for data fetching\n- Implementing mutations with optimistic updates\n- Error handling and cache invalidation\n\n**Also load building-with-medusa when:** Building the backend API routes that the storefront calls\n\n## CRITICAL: Load Reference Files When Needed\n\n**The quick reference below is NOT sufficient for implementation.** You MUST load the reference file before writing storefront integration code.\n\n**Load this reference when implementing storefront features:**\n\n- **Calling API routes?** → MUST load `references\u002Ffrontend-integration.md` first\n- **Using SDK?** → MUST load `references\u002Ffrontend-integration.md` first\n- **Implementing React Query?** → MUST load `references\u002Ffrontend-integration.md` first\n\n## Rule Categories by Priority\n\n| Priority | Category | Impact | Prefix |\n|----------|----------|--------|--------|\n| 1 | SDK Usage | CRITICAL | `sdk-` |\n| 2 | React Query Patterns | HIGH | `query-` |\n| 3 | Data Display | HIGH (includes CRITICAL price rule) | `display-` |\n| 4 | Error Handling | MEDIUM | `error-` |\n\n## Quick Reference\n\n### 1. SDK Usage (CRITICAL)\n\n- `sdk-always-use` - **ALWAYS use the Medusa JS SDK for ALL API requests** - NEVER use regular fetch()\n- `sdk-existing-methods` - For built-in endpoints, use existing SDK methods (`sdk.store.product.list()`, `sdk.admin.order.retrieve()`)\n- `sdk-client-fetch` - For custom API routes, use `sdk.client.fetch()`\n- `sdk-required-headers` - SDK automatically adds required headers (publishable API key for store, auth for admin) - regular fetch() missing these headers causes errors\n- `sdk-no-json-stringify` - **NEVER use JSON.stringify() on body** - SDK handles serialization automatically\n- `sdk-plain-objects` - Pass plain JavaScript objects to body, not strings\n- `sdk-locate-first` - Always locate where SDK is instantiated in the project before using it\n\n### 2. React Query Patterns (HIGH)\n\n- `query-use-query` - Use `useQuery` for GET requests (data fetching)\n- `query-use-mutation` - Use `useMutation` for POST\u002FDELETE requests (mutations)\n- `query-invalidate` - Invalidate queries in `onSuccess` to refresh data after mutations\n- `query-keys-hierarchical` - Structure query keys hierarchically for effective cache management\n- `query-loading-states` - Always handle `isLoading`, `isPending`, `isError` states\n\n### 3. Data Display (HIGH)\n\n- `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\n\n### 4. Error Handling (MEDIUM)\n\n- `error-on-error` - Implement `onError` callback in mutations to handle failures\n- `error-display` - Show error messages to users when mutations fail\n- `error-rollback` - Use optimistic updates with rollback on error for better UX\n\n## Critical SDK Pattern\n\n**ALWAYS pass plain objects to the SDK - NEVER use JSON.stringify():**\n\n```typescript\n\u002F\u002F ✅ CORRECT - Plain object\nawait sdk.client.fetch(\"\u002Fstore\u002Freviews\", {\n  method: \"POST\",\n  body: {\n    product_id: \"prod_123\",\n    rating: 5,\n  }\n})\n\n\u002F\u002F ❌ WRONG - JSON.stringify breaks the request\nawait sdk.client.fetch(\"\u002Fstore\u002Freviews\", {\n  method: \"POST\",\n  body: JSON.stringify({  \u002F\u002F ❌ DON'T DO THIS!\n    product_id: \"prod_123\",\n    rating: 5,\n  })\n})\n```\n\n**Why this matters:**\n- The SDK handles JSON serialization automatically\n- Using JSON.stringify() will double-serialize and break the request\n- The server won't be able to parse the body\n\n## Common Mistakes Checklist\n\nBefore implementing, verify you're NOT doing these:\n\n**SDK Usage:**\n- [ ] Using regular fetch() instead of the Medusa JS SDK (causes missing header errors)\n- [ ] Not using existing SDK methods for built-in endpoints (e.g., using sdk.client.fetch(\"\u002Fstore\u002Fproducts\") instead of sdk.store.product.list())\n- [ ] Using JSON.stringify() on the body parameter\n- [ ] Manually setting Content-Type headers (SDK adds them)\n- [ ] Hardcoding SDK import paths (locate in project first)\n- [ ] Not using sdk.client.fetch() for custom routes\n\n**React Query:**\n- [ ] Not invalidating queries after mutations\n- [ ] Using flat query keys instead of hierarchical\n- [ ] Not handling loading and error states\n- [ ] Forgetting to disable buttons during mutations (isPending)\n\n**Data Display:**\n- [ ] **CRITICAL**: Dividing prices by 100 when displaying (prices are stored as-is: $49.99 = 49.99, NOT in cents)\n\n**Error Handling:**\n- [ ] Not implementing onError callbacks\n- [ ] Not showing error messages to users\n- [ ] Not handling network failures gracefully\n\n## How to Use\n\n**For detailed patterns and examples, load reference file:**\n\n```\nreferences\u002Ffrontend-integration.md - SDK usage, React Query patterns, API integration\n```\n\nThe reference file contains:\n- Step-by-step SDK integration patterns\n- Complete React Query examples\n- Correct vs incorrect code examples\n- Query key best practices\n- Optimistic update patterns\n- Error handling strategies\n\n## When to Use MedusaDocs MCP Server\n\n**Use this skill for (PRIMARY SOURCE):**\n- How to call custom API routes from storefront\n- SDK usage patterns (sdk.client.fetch)\n- React Query integration patterns\n- Common mistakes and anti-patterns\n\n**Use MedusaDocs MCP server for (SECONDARY SOURCE):**\n- Built-in SDK methods (sdk.admin.*, sdk.store.*)\n- Official Medusa SDK API reference\n- Framework-specific configuration options\n\n**Why skills come first:**\n- Skills contain critical patterns like \"don't use JSON.stringify\" that MCP doesn't emphasize\n- Skills show correct vs incorrect patterns; MCP shows what's possible\n- Planning requires understanding patterns, not just API reference\n\n## Integration with Backend\n\n**⚠️ CRITICAL: ALWAYS use the Medusa JS SDK - NEVER use regular fetch()**\n\nWhen building features that span backend and frontend:\n\n1. **Backend (building-with-medusa skill):** Module → Workflow → API Route\n2. **Storefront (this skill):** SDK → React Query → UI Components\n3. **Connection:**\n   - Built-in endpoints: Use existing SDK methods (`sdk.store.product.list()`)\n   - Custom API routes: Use `sdk.client.fetch(\"\u002Fstore\u002Fmy-route\")`\n   - **NEVER use regular fetch()** - missing publishable API key causes errors\n\n**Why the SDK is required:**\n- Store routes need `x-publishable-api-key` header\n- Admin routes need `Authorization` and session headers\n- SDK handles all required headers automatically\n- Regular fetch() without headers → authentication\u002Fauthorization errors\n\nSee `building-with-medusa` for backend API route patterns.\n",{"data":44,"body":45},{"name":4,"description":6},{"type":46,"children":47},"root",[48,57,63,70,79,109,119,125,135,143,195,201,347,353,360,475,481,584,590,609,615,659,665,673,1102,1110,1128,1134,1139,1147,1209,1217,1257,1265,1284,1292,1323,1329,1337,1347,1352,1385,1391,1399,1422,1430,1455,1463,1481,1487,1495,1500,1567,1575,1614,1627],{"type":49,"tag":50,"props":51,"children":53},"element","h1",{"id":52},"medusa-storefront-development",[54],{"type":55,"value":56},"text","Medusa Storefront Development",{"type":49,"tag":58,"props":59,"children":60},"p",{},[61],{"type":55,"value":62},"Frontend integration guide for building storefronts with Medusa. Covers SDK usage, React Query patterns, and calling custom API routes.",{"type":49,"tag":64,"props":65,"children":67},"h2",{"id":66},"when-to-apply",[68],{"type":55,"value":69},"When to Apply",{"type":49,"tag":58,"props":71,"children":72},{},[73],{"type":49,"tag":74,"props":75,"children":76},"strong",{},[77],{"type":55,"value":78},"Load this skill for ANY storefront development task, including:",{"type":49,"tag":80,"props":81,"children":82},"ul",{},[83,89,94,99,104],{"type":49,"tag":84,"props":85,"children":86},"li",{},[87],{"type":55,"value":88},"Calling custom Medusa API routes from the storefront",{"type":49,"tag":84,"props":90,"children":91},{},[92],{"type":55,"value":93},"Integrating Medusa SDK in frontend applications",{"type":49,"tag":84,"props":95,"children":96},{},[97],{"type":55,"value":98},"Using React Query for data fetching",{"type":49,"tag":84,"props":100,"children":101},{},[102],{"type":55,"value":103},"Implementing mutations with optimistic updates",{"type":49,"tag":84,"props":105,"children":106},{},[107],{"type":55,"value":108},"Error handling and cache invalidation",{"type":49,"tag":58,"props":110,"children":111},{},[112,117],{"type":49,"tag":74,"props":113,"children":114},{},[115],{"type":55,"value":116},"Also load building-with-medusa when:",{"type":55,"value":118}," Building the backend API routes that the storefront calls",{"type":49,"tag":64,"props":120,"children":122},{"id":121},"critical-load-reference-files-when-needed",[123],{"type":55,"value":124},"CRITICAL: Load Reference Files When Needed",{"type":49,"tag":58,"props":126,"children":127},{},[128,133],{"type":49,"tag":74,"props":129,"children":130},{},[131],{"type":55,"value":132},"The quick reference below is NOT sufficient for implementation.",{"type":55,"value":134}," You MUST load the reference file before writing storefront integration code.",{"type":49,"tag":58,"props":136,"children":137},{},[138],{"type":49,"tag":74,"props":139,"children":140},{},[141],{"type":55,"value":142},"Load this reference when implementing storefront features:",{"type":49,"tag":80,"props":144,"children":145},{},[146,165,180],{"type":49,"tag":84,"props":147,"children":148},{},[149,154,156,163],{"type":49,"tag":74,"props":150,"children":151},{},[152],{"type":55,"value":153},"Calling API routes?",{"type":55,"value":155}," → MUST load ",{"type":49,"tag":157,"props":158,"children":160},"code",{"className":159},[],[161],{"type":55,"value":162},"references\u002Ffrontend-integration.md",{"type":55,"value":164}," first",{"type":49,"tag":84,"props":166,"children":167},{},[168,173,174,179],{"type":49,"tag":74,"props":169,"children":170},{},[171],{"type":55,"value":172},"Using SDK?",{"type":55,"value":155},{"type":49,"tag":157,"props":175,"children":177},{"className":176},[],[178],{"type":55,"value":162},{"type":55,"value":164},{"type":49,"tag":84,"props":181,"children":182},{},[183,188,189,194],{"type":49,"tag":74,"props":184,"children":185},{},[186],{"type":55,"value":187},"Implementing React Query?",{"type":55,"value":155},{"type":49,"tag":157,"props":190,"children":192},{"className":191},[],[193],{"type":55,"value":162},{"type":55,"value":164},{"type":49,"tag":64,"props":196,"children":198},{"id":197},"rule-categories-by-priority",[199],{"type":55,"value":200},"Rule Categories by Priority",{"type":49,"tag":202,"props":203,"children":204},"table",{},[205,234],{"type":49,"tag":206,"props":207,"children":208},"thead",{},[209],{"type":49,"tag":210,"props":211,"children":212},"tr",{},[213,219,224,229],{"type":49,"tag":214,"props":215,"children":216},"th",{},[217],{"type":55,"value":218},"Priority",{"type":49,"tag":214,"props":220,"children":221},{},[222],{"type":55,"value":223},"Category",{"type":49,"tag":214,"props":225,"children":226},{},[227],{"type":55,"value":228},"Impact",{"type":49,"tag":214,"props":230,"children":231},{},[232],{"type":55,"value":233},"Prefix",{"type":49,"tag":235,"props":236,"children":237},"tbody",{},[238,266,293,320],{"type":49,"tag":210,"props":239,"children":240},{},[241,247,252,257],{"type":49,"tag":242,"props":243,"children":244},"td",{},[245],{"type":55,"value":246},"1",{"type":49,"tag":242,"props":248,"children":249},{},[250],{"type":55,"value":251},"SDK Usage",{"type":49,"tag":242,"props":253,"children":254},{},[255],{"type":55,"value":256},"CRITICAL",{"type":49,"tag":242,"props":258,"children":259},{},[260],{"type":49,"tag":157,"props":261,"children":263},{"className":262},[],[264],{"type":55,"value":265},"sdk-",{"type":49,"tag":210,"props":267,"children":268},{},[269,274,279,284],{"type":49,"tag":242,"props":270,"children":271},{},[272],{"type":55,"value":273},"2",{"type":49,"tag":242,"props":275,"children":276},{},[277],{"type":55,"value":278},"React Query Patterns",{"type":49,"tag":242,"props":280,"children":281},{},[282],{"type":55,"value":283},"HIGH",{"type":49,"tag":242,"props":285,"children":286},{},[287],{"type":49,"tag":157,"props":288,"children":290},{"className":289},[],[291],{"type":55,"value":292},"query-",{"type":49,"tag":210,"props":294,"children":295},{},[296,301,306,311],{"type":49,"tag":242,"props":297,"children":298},{},[299],{"type":55,"value":300},"3",{"type":49,"tag":242,"props":302,"children":303},{},[304],{"type":55,"value":305},"Data Display",{"type":49,"tag":242,"props":307,"children":308},{},[309],{"type":55,"value":310},"HIGH (includes CRITICAL price rule)",{"type":49,"tag":242,"props":312,"children":313},{},[314],{"type":49,"tag":157,"props":315,"children":317},{"className":316},[],[318],{"type":55,"value":319},"display-",{"type":49,"tag":210,"props":321,"children":322},{},[323,328,333,338],{"type":49,"tag":242,"props":324,"children":325},{},[326],{"type":55,"value":327},"4",{"type":49,"tag":242,"props":329,"children":330},{},[331],{"type":55,"value":332},"Error Handling",{"type":49,"tag":242,"props":334,"children":335},{},[336],{"type":55,"value":337},"MEDIUM",{"type":49,"tag":242,"props":339,"children":340},{},[341],{"type":49,"tag":157,"props":342,"children":344},{"className":343},[],[345],{"type":55,"value":346},"error-",{"type":49,"tag":64,"props":348,"children":350},{"id":349},"quick-reference",[351],{"type":55,"value":352},"Quick Reference",{"type":49,"tag":354,"props":355,"children":357},"h3",{"id":356},"_1-sdk-usage-critical",[358],{"type":55,"value":359},"1. SDK Usage (CRITICAL)",{"type":49,"tag":80,"props":361,"children":362},{},[363,381,408,425,436,453,464],{"type":49,"tag":84,"props":364,"children":365},{},[366,372,374,379],{"type":49,"tag":157,"props":367,"children":369},{"className":368},[],[370],{"type":55,"value":371},"sdk-always-use",{"type":55,"value":373}," - ",{"type":49,"tag":74,"props":375,"children":376},{},[377],{"type":55,"value":378},"ALWAYS use the Medusa JS SDK for ALL API requests",{"type":55,"value":380}," - NEVER use regular fetch()",{"type":49,"tag":84,"props":382,"children":383},{},[384,390,392,398,400,406],{"type":49,"tag":157,"props":385,"children":387},{"className":386},[],[388],{"type":55,"value":389},"sdk-existing-methods",{"type":55,"value":391}," - For built-in endpoints, use existing SDK methods (",{"type":49,"tag":157,"props":393,"children":395},{"className":394},[],[396],{"type":55,"value":397},"sdk.store.product.list()",{"type":55,"value":399},", ",{"type":49,"tag":157,"props":401,"children":403},{"className":402},[],[404],{"type":55,"value":405},"sdk.admin.order.retrieve()",{"type":55,"value":407},")",{"type":49,"tag":84,"props":409,"children":410},{},[411,417,419],{"type":49,"tag":157,"props":412,"children":414},{"className":413},[],[415],{"type":55,"value":416},"sdk-client-fetch",{"type":55,"value":418}," - For custom API routes, use ",{"type":49,"tag":157,"props":420,"children":422},{"className":421},[],[423],{"type":55,"value":424},"sdk.client.fetch()",{"type":49,"tag":84,"props":426,"children":427},{},[428,434],{"type":49,"tag":157,"props":429,"children":431},{"className":430},[],[432],{"type":55,"value":433},"sdk-required-headers",{"type":55,"value":435}," - SDK automatically adds required headers (publishable API key for store, auth for admin) - regular fetch() missing these headers causes errors",{"type":49,"tag":84,"props":437,"children":438},{},[439,445,446,451],{"type":49,"tag":157,"props":440,"children":442},{"className":441},[],[443],{"type":55,"value":444},"sdk-no-json-stringify",{"type":55,"value":373},{"type":49,"tag":74,"props":447,"children":448},{},[449],{"type":55,"value":450},"NEVER use JSON.stringify() on body",{"type":55,"value":452}," - SDK handles serialization automatically",{"type":49,"tag":84,"props":454,"children":455},{},[456,462],{"type":49,"tag":157,"props":457,"children":459},{"className":458},[],[460],{"type":55,"value":461},"sdk-plain-objects",{"type":55,"value":463}," - Pass plain JavaScript objects to body, not strings",{"type":49,"tag":84,"props":465,"children":466},{},[467,473],{"type":49,"tag":157,"props":468,"children":470},{"className":469},[],[471],{"type":55,"value":472},"sdk-locate-first",{"type":55,"value":474}," - Always locate where SDK is instantiated in the project before using it",{"type":49,"tag":354,"props":476,"children":478},{"id":477},"_2-react-query-patterns-high",[479],{"type":55,"value":480},"2. React Query Patterns (HIGH)",{"type":49,"tag":80,"props":482,"children":483},{},[484,503,521,540,551],{"type":49,"tag":84,"props":485,"children":486},{},[487,493,495,501],{"type":49,"tag":157,"props":488,"children":490},{"className":489},[],[491],{"type":55,"value":492},"query-use-query",{"type":55,"value":494}," - Use ",{"type":49,"tag":157,"props":496,"children":498},{"className":497},[],[499],{"type":55,"value":500},"useQuery",{"type":55,"value":502}," for GET requests (data fetching)",{"type":49,"tag":84,"props":504,"children":505},{},[506,512,513,519],{"type":49,"tag":157,"props":507,"children":509},{"className":508},[],[510],{"type":55,"value":511},"query-use-mutation",{"type":55,"value":494},{"type":49,"tag":157,"props":514,"children":516},{"className":515},[],[517],{"type":55,"value":518},"useMutation",{"type":55,"value":520}," for POST\u002FDELETE requests (mutations)",{"type":49,"tag":84,"props":522,"children":523},{},[524,530,532,538],{"type":49,"tag":157,"props":525,"children":527},{"className":526},[],[528],{"type":55,"value":529},"query-invalidate",{"type":55,"value":531}," - Invalidate queries in ",{"type":49,"tag":157,"props":533,"children":535},{"className":534},[],[536],{"type":55,"value":537},"onSuccess",{"type":55,"value":539}," to refresh data after mutations",{"type":49,"tag":84,"props":541,"children":542},{},[543,549],{"type":49,"tag":157,"props":544,"children":546},{"className":545},[],[547],{"type":55,"value":548},"query-keys-hierarchical",{"type":55,"value":550}," - Structure query keys hierarchically for effective cache management",{"type":49,"tag":84,"props":552,"children":553},{},[554,560,562,568,569,575,576,582],{"type":49,"tag":157,"props":555,"children":557},{"className":556},[],[558],{"type":55,"value":559},"query-loading-states",{"type":55,"value":561}," - Always handle ",{"type":49,"tag":157,"props":563,"children":565},{"className":564},[],[566],{"type":55,"value":567},"isLoading",{"type":55,"value":399},{"type":49,"tag":157,"props":570,"children":572},{"className":571},[],[573],{"type":55,"value":574},"isPending",{"type":55,"value":399},{"type":49,"tag":157,"props":577,"children":579},{"className":578},[],[580],{"type":55,"value":581},"isError",{"type":55,"value":583}," states",{"type":49,"tag":354,"props":585,"children":587},{"id":586},"_3-data-display-high",[588],{"type":55,"value":589},"3. Data Display (HIGH)",{"type":49,"tag":80,"props":591,"children":592},{},[593],{"type":49,"tag":84,"props":594,"children":595},{},[596,602,603,607],{"type":49,"tag":157,"props":597,"children":599},{"className":598},[],[600],{"type":55,"value":601},"display-price-format",{"type":55,"value":373},{"type":49,"tag":74,"props":604,"children":605},{},[606],{"type":55,"value":256},{"type":55,"value":608},": Prices from Medusa are stored as-is ($49.99 = 49.99, NOT in cents). Display them directly - NEVER divide by 100",{"type":49,"tag":354,"props":610,"children":612},{"id":611},"_4-error-handling-medium",[613],{"type":55,"value":614},"4. Error Handling (MEDIUM)",{"type":49,"tag":80,"props":616,"children":617},{},[618,637,648],{"type":49,"tag":84,"props":619,"children":620},{},[621,627,629,635],{"type":49,"tag":157,"props":622,"children":624},{"className":623},[],[625],{"type":55,"value":626},"error-on-error",{"type":55,"value":628}," - Implement ",{"type":49,"tag":157,"props":630,"children":632},{"className":631},[],[633],{"type":55,"value":634},"onError",{"type":55,"value":636}," callback in mutations to handle failures",{"type":49,"tag":84,"props":638,"children":639},{},[640,646],{"type":49,"tag":157,"props":641,"children":643},{"className":642},[],[644],{"type":55,"value":645},"error-display",{"type":55,"value":647}," - Show error messages to users when mutations fail",{"type":49,"tag":84,"props":649,"children":650},{},[651,657],{"type":49,"tag":157,"props":652,"children":654},{"className":653},[],[655],{"type":55,"value":656},"error-rollback",{"type":55,"value":658}," - Use optimistic updates with rollback on error for better UX",{"type":49,"tag":64,"props":660,"children":662},{"id":661},"critical-sdk-pattern",[663],{"type":55,"value":664},"Critical SDK Pattern",{"type":49,"tag":58,"props":666,"children":667},{},[668],{"type":49,"tag":74,"props":669,"children":670},{},[671],{"type":55,"value":672},"ALWAYS pass plain objects to the SDK - NEVER use JSON.stringify():",{"type":49,"tag":674,"props":675,"children":680},"pre",{"className":676,"code":677,"language":678,"meta":679,"style":679},"language-typescript shiki shiki-themes material-theme-lighter material-theme material-theme-palenight","\u002F\u002F ✅ CORRECT - Plain object\nawait sdk.client.fetch(\"\u002Fstore\u002Freviews\", {\n  method: \"POST\",\n  body: {\n    product_id: \"prod_123\",\n    rating: 5,\n  }\n})\n\n\u002F\u002F ❌ WRONG - JSON.stringify breaks the request\nawait sdk.client.fetch(\"\u002Fstore\u002Freviews\", {\n  method: \"POST\",\n  body: JSON.stringify({  \u002F\u002F ❌ DON'T DO THIS!\n    product_id: \"prod_123\",\n    rating: 5,\n  })\n})\n","typescript","",[681],{"type":49,"tag":157,"props":682,"children":683},{"__ignoreMap":679},[684,696,763,797,814,844,867,876,890,900,909,961,989,1029,1057,1077,1090],{"type":49,"tag":685,"props":686,"children":689},"span",{"class":687,"line":688},"line",1,[690],{"type":49,"tag":685,"props":691,"children":693},{"style":692},"--shiki-light:#90A4AE;--shiki-light-font-style:italic;--shiki-default:#546E7A;--shiki-default-font-style:italic;--shiki-dark:#676E95;--shiki-dark-font-style:italic",[694],{"type":55,"value":695},"\u002F\u002F ✅ CORRECT - Plain object\n",{"type":49,"tag":685,"props":697,"children":699},{"class":687,"line":698},2,[700,706,712,718,723,727,733,738,743,749,753,758],{"type":49,"tag":685,"props":701,"children":703},{"style":702},"--shiki-light:#39ADB5;--shiki-light-font-style:italic;--shiki-default:#89DDFF;--shiki-default-font-style:italic;--shiki-dark:#89DDFF;--shiki-dark-font-style:italic",[704],{"type":55,"value":705},"await",{"type":49,"tag":685,"props":707,"children":709},{"style":708},"--shiki-light:#90A4AE;--shiki-default:#EEFFFF;--shiki-dark:#BABED8",[710],{"type":55,"value":711}," sdk",{"type":49,"tag":685,"props":713,"children":715},{"style":714},"--shiki-light:#39ADB5;--shiki-default:#89DDFF;--shiki-dark:#89DDFF",[716],{"type":55,"value":717},".",{"type":49,"tag":685,"props":719,"children":720},{"style":708},[721],{"type":55,"value":722},"client",{"type":49,"tag":685,"props":724,"children":725},{"style":714},[726],{"type":55,"value":717},{"type":49,"tag":685,"props":728,"children":730},{"style":729},"--shiki-light:#6182B8;--shiki-default:#82AAFF;--shiki-dark:#82AAFF",[731],{"type":55,"value":732},"fetch",{"type":49,"tag":685,"props":734,"children":735},{"style":708},[736],{"type":55,"value":737},"(",{"type":49,"tag":685,"props":739,"children":740},{"style":714},[741],{"type":55,"value":742},"\"",{"type":49,"tag":685,"props":744,"children":746},{"style":745},"--shiki-light:#91B859;--shiki-default:#C3E88D;--shiki-dark:#C3E88D",[747],{"type":55,"value":748},"\u002Fstore\u002Freviews",{"type":49,"tag":685,"props":750,"children":751},{"style":714},[752],{"type":55,"value":742},{"type":49,"tag":685,"props":754,"children":755},{"style":714},[756],{"type":55,"value":757},",",{"type":49,"tag":685,"props":759,"children":760},{"style":714},[761],{"type":55,"value":762}," {\n",{"type":49,"tag":685,"props":764,"children":766},{"class":687,"line":765},3,[767,773,778,783,788,792],{"type":49,"tag":685,"props":768,"children":770},{"style":769},"--shiki-light:#E53935;--shiki-default:#F07178;--shiki-dark:#F07178",[771],{"type":55,"value":772},"  method",{"type":49,"tag":685,"props":774,"children":775},{"style":714},[776],{"type":55,"value":777},":",{"type":49,"tag":685,"props":779,"children":780},{"style":714},[781],{"type":55,"value":782}," \"",{"type":49,"tag":685,"props":784,"children":785},{"style":745},[786],{"type":55,"value":787},"POST",{"type":49,"tag":685,"props":789,"children":790},{"style":714},[791],{"type":55,"value":742},{"type":49,"tag":685,"props":793,"children":794},{"style":714},[795],{"type":55,"value":796},",\n",{"type":49,"tag":685,"props":798,"children":800},{"class":687,"line":799},4,[801,806,810],{"type":49,"tag":685,"props":802,"children":803},{"style":769},[804],{"type":55,"value":805},"  body",{"type":49,"tag":685,"props":807,"children":808},{"style":714},[809],{"type":55,"value":777},{"type":49,"tag":685,"props":811,"children":812},{"style":714},[813],{"type":55,"value":762},{"type":49,"tag":685,"props":815,"children":817},{"class":687,"line":816},5,[818,823,827,831,836,840],{"type":49,"tag":685,"props":819,"children":820},{"style":769},[821],{"type":55,"value":822},"    product_id",{"type":49,"tag":685,"props":824,"children":825},{"style":714},[826],{"type":55,"value":777},{"type":49,"tag":685,"props":828,"children":829},{"style":714},[830],{"type":55,"value":782},{"type":49,"tag":685,"props":832,"children":833},{"style":745},[834],{"type":55,"value":835},"prod_123",{"type":49,"tag":685,"props":837,"children":838},{"style":714},[839],{"type":55,"value":742},{"type":49,"tag":685,"props":841,"children":842},{"style":714},[843],{"type":55,"value":796},{"type":49,"tag":685,"props":845,"children":847},{"class":687,"line":846},6,[848,853,857,863],{"type":49,"tag":685,"props":849,"children":850},{"style":769},[851],{"type":55,"value":852},"    rating",{"type":49,"tag":685,"props":854,"children":855},{"style":714},[856],{"type":55,"value":777},{"type":49,"tag":685,"props":858,"children":860},{"style":859},"--shiki-light:#F76D47;--shiki-default:#F78C6C;--shiki-dark:#F78C6C",[861],{"type":55,"value":862}," 5",{"type":49,"tag":685,"props":864,"children":865},{"style":714},[866],{"type":55,"value":796},{"type":49,"tag":685,"props":868,"children":870},{"class":687,"line":869},7,[871],{"type":49,"tag":685,"props":872,"children":873},{"style":714},[874],{"type":55,"value":875},"  }\n",{"type":49,"tag":685,"props":877,"children":879},{"class":687,"line":878},8,[880,885],{"type":49,"tag":685,"props":881,"children":882},{"style":714},[883],{"type":55,"value":884},"}",{"type":49,"tag":685,"props":886,"children":887},{"style":708},[888],{"type":55,"value":889},")\n",{"type":49,"tag":685,"props":891,"children":893},{"class":687,"line":892},9,[894],{"type":49,"tag":685,"props":895,"children":897},{"emptyLinePlaceholder":896},true,[898],{"type":55,"value":899},"\n",{"type":49,"tag":685,"props":901,"children":903},{"class":687,"line":902},10,[904],{"type":49,"tag":685,"props":905,"children":906},{"style":692},[907],{"type":55,"value":908},"\u002F\u002F ❌ WRONG - JSON.stringify breaks the request\n",{"type":49,"tag":685,"props":910,"children":912},{"class":687,"line":911},11,[913,917,921,925,929,933,937,941,945,949,953,957],{"type":49,"tag":685,"props":914,"children":915},{"style":702},[916],{"type":55,"value":705},{"type":49,"tag":685,"props":918,"children":919},{"style":708},[920],{"type":55,"value":711},{"type":49,"tag":685,"props":922,"children":923},{"style":714},[924],{"type":55,"value":717},{"type":49,"tag":685,"props":926,"children":927},{"style":708},[928],{"type":55,"value":722},{"type":49,"tag":685,"props":930,"children":931},{"style":714},[932],{"type":55,"value":717},{"type":49,"tag":685,"props":934,"children":935},{"style":729},[936],{"type":55,"value":732},{"type":49,"tag":685,"props":938,"children":939},{"style":708},[940],{"type":55,"value":737},{"type":49,"tag":685,"props":942,"children":943},{"style":714},[944],{"type":55,"value":742},{"type":49,"tag":685,"props":946,"children":947},{"style":745},[948],{"type":55,"value":748},{"type":49,"tag":685,"props":950,"children":951},{"style":714},[952],{"type":55,"value":742},{"type":49,"tag":685,"props":954,"children":955},{"style":714},[956],{"type":55,"value":757},{"type":49,"tag":685,"props":958,"children":959},{"style":714},[960],{"type":55,"value":762},{"type":49,"tag":685,"props":962,"children":964},{"class":687,"line":963},12,[965,969,973,977,981,985],{"type":49,"tag":685,"props":966,"children":967},{"style":769},[968],{"type":55,"value":772},{"type":49,"tag":685,"props":970,"children":971},{"style":714},[972],{"type":55,"value":777},{"type":49,"tag":685,"props":974,"children":975},{"style":714},[976],{"type":55,"value":782},{"type":49,"tag":685,"props":978,"children":979},{"style":745},[980],{"type":55,"value":787},{"type":49,"tag":685,"props":982,"children":983},{"style":714},[984],{"type":55,"value":742},{"type":49,"tag":685,"props":986,"children":987},{"style":714},[988],{"type":55,"value":796},{"type":49,"tag":685,"props":990,"children":992},{"class":687,"line":991},13,[993,997,1001,1006,1010,1015,1019,1024],{"type":49,"tag":685,"props":994,"children":995},{"style":769},[996],{"type":55,"value":805},{"type":49,"tag":685,"props":998,"children":999},{"style":714},[1000],{"type":55,"value":777},{"type":49,"tag":685,"props":1002,"children":1003},{"style":708},[1004],{"type":55,"value":1005}," JSON",{"type":49,"tag":685,"props":1007,"children":1008},{"style":714},[1009],{"type":55,"value":717},{"type":49,"tag":685,"props":1011,"children":1012},{"style":729},[1013],{"type":55,"value":1014},"stringify",{"type":49,"tag":685,"props":1016,"children":1017},{"style":708},[1018],{"type":55,"value":737},{"type":49,"tag":685,"props":1020,"children":1021},{"style":714},[1022],{"type":55,"value":1023},"{",{"type":49,"tag":685,"props":1025,"children":1026},{"style":692},[1027],{"type":55,"value":1028},"  \u002F\u002F ❌ DON'T DO THIS!\n",{"type":49,"tag":685,"props":1030,"children":1032},{"class":687,"line":1031},14,[1033,1037,1041,1045,1049,1053],{"type":49,"tag":685,"props":1034,"children":1035},{"style":769},[1036],{"type":55,"value":822},{"type":49,"tag":685,"props":1038,"children":1039},{"style":714},[1040],{"type":55,"value":777},{"type":49,"tag":685,"props":1042,"children":1043},{"style":714},[1044],{"type":55,"value":782},{"type":49,"tag":685,"props":1046,"children":1047},{"style":745},[1048],{"type":55,"value":835},{"type":49,"tag":685,"props":1050,"children":1051},{"style":714},[1052],{"type":55,"value":742},{"type":49,"tag":685,"props":1054,"children":1055},{"style":714},[1056],{"type":55,"value":796},{"type":49,"tag":685,"props":1058,"children":1060},{"class":687,"line":1059},15,[1061,1065,1069,1073],{"type":49,"tag":685,"props":1062,"children":1063},{"style":769},[1064],{"type":55,"value":852},{"type":49,"tag":685,"props":1066,"children":1067},{"style":714},[1068],{"type":55,"value":777},{"type":49,"tag":685,"props":1070,"children":1071},{"style":859},[1072],{"type":55,"value":862},{"type":49,"tag":685,"props":1074,"children":1075},{"style":714},[1076],{"type":55,"value":796},{"type":49,"tag":685,"props":1078,"children":1080},{"class":687,"line":1079},16,[1081,1086],{"type":49,"tag":685,"props":1082,"children":1083},{"style":714},[1084],{"type":55,"value":1085},"  }",{"type":49,"tag":685,"props":1087,"children":1088},{"style":708},[1089],{"type":55,"value":889},{"type":49,"tag":685,"props":1091,"children":1093},{"class":687,"line":1092},17,[1094,1098],{"type":49,"tag":685,"props":1095,"children":1096},{"style":714},[1097],{"type":55,"value":884},{"type":49,"tag":685,"props":1099,"children":1100},{"style":708},[1101],{"type":55,"value":889},{"type":49,"tag":58,"props":1103,"children":1104},{},[1105],{"type":49,"tag":74,"props":1106,"children":1107},{},[1108],{"type":55,"value":1109},"Why this matters:",{"type":49,"tag":80,"props":1111,"children":1112},{},[1113,1118,1123],{"type":49,"tag":84,"props":1114,"children":1115},{},[1116],{"type":55,"value":1117},"The SDK handles JSON serialization automatically",{"type":49,"tag":84,"props":1119,"children":1120},{},[1121],{"type":55,"value":1122},"Using JSON.stringify() will double-serialize and break the request",{"type":49,"tag":84,"props":1124,"children":1125},{},[1126],{"type":55,"value":1127},"The server won't be able to parse the body",{"type":49,"tag":64,"props":1129,"children":1131},{"id":1130},"common-mistakes-checklist",[1132],{"type":55,"value":1133},"Common Mistakes Checklist",{"type":49,"tag":58,"props":1135,"children":1136},{},[1137],{"type":55,"value":1138},"Before implementing, verify you're NOT doing these:",{"type":49,"tag":58,"props":1140,"children":1141},{},[1142],{"type":49,"tag":74,"props":1143,"children":1144},{},[1145],{"type":55,"value":1146},"SDK Usage:",{"type":49,"tag":80,"props":1148,"children":1151},{"className":1149},[1150],"contains-task-list",[1152,1164,1173,1182,1191,1200],{"type":49,"tag":84,"props":1153,"children":1156},{"className":1154},[1155],"task-list-item",[1157,1162],{"type":49,"tag":1158,"props":1159,"children":1161},"input",{"disabled":896,"type":1160},"checkbox",[],{"type":55,"value":1163}," Using regular fetch() instead of the Medusa JS SDK (causes missing header errors)",{"type":49,"tag":84,"props":1165,"children":1167},{"className":1166},[1155],[1168,1171],{"type":49,"tag":1158,"props":1169,"children":1170},{"disabled":896,"type":1160},[],{"type":55,"value":1172}," Not using existing SDK methods for built-in endpoints (e.g., using sdk.client.fetch(\"\u002Fstore\u002Fproducts\") instead of sdk.store.product.list())",{"type":49,"tag":84,"props":1174,"children":1176},{"className":1175},[1155],[1177,1180],{"type":49,"tag":1158,"props":1178,"children":1179},{"disabled":896,"type":1160},[],{"type":55,"value":1181}," Using JSON.stringify() on the body parameter",{"type":49,"tag":84,"props":1183,"children":1185},{"className":1184},[1155],[1186,1189],{"type":49,"tag":1158,"props":1187,"children":1188},{"disabled":896,"type":1160},[],{"type":55,"value":1190}," Manually setting Content-Type headers (SDK adds them)",{"type":49,"tag":84,"props":1192,"children":1194},{"className":1193},[1155],[1195,1198],{"type":49,"tag":1158,"props":1196,"children":1197},{"disabled":896,"type":1160},[],{"type":55,"value":1199}," Hardcoding SDK import paths (locate in project first)",{"type":49,"tag":84,"props":1201,"children":1203},{"className":1202},[1155],[1204,1207],{"type":49,"tag":1158,"props":1205,"children":1206},{"disabled":896,"type":1160},[],{"type":55,"value":1208}," Not using sdk.client.fetch() for custom routes",{"type":49,"tag":58,"props":1210,"children":1211},{},[1212],{"type":49,"tag":74,"props":1213,"children":1214},{},[1215],{"type":55,"value":1216},"React Query:",{"type":49,"tag":80,"props":1218,"children":1220},{"className":1219},[1150],[1221,1230,1239,1248],{"type":49,"tag":84,"props":1222,"children":1224},{"className":1223},[1155],[1225,1228],{"type":49,"tag":1158,"props":1226,"children":1227},{"disabled":896,"type":1160},[],{"type":55,"value":1229}," Not invalidating queries after mutations",{"type":49,"tag":84,"props":1231,"children":1233},{"className":1232},[1155],[1234,1237],{"type":49,"tag":1158,"props":1235,"children":1236},{"disabled":896,"type":1160},[],{"type":55,"value":1238}," Using flat query keys instead of hierarchical",{"type":49,"tag":84,"props":1240,"children":1242},{"className":1241},[1155],[1243,1246],{"type":49,"tag":1158,"props":1244,"children":1245},{"disabled":896,"type":1160},[],{"type":55,"value":1247}," Not handling loading and error states",{"type":49,"tag":84,"props":1249,"children":1251},{"className":1250},[1155],[1252,1255],{"type":49,"tag":1158,"props":1253,"children":1254},{"disabled":896,"type":1160},[],{"type":55,"value":1256}," Forgetting to disable buttons during mutations (isPending)",{"type":49,"tag":58,"props":1258,"children":1259},{},[1260],{"type":49,"tag":74,"props":1261,"children":1262},{},[1263],{"type":55,"value":1264},"Data Display:",{"type":49,"tag":80,"props":1266,"children":1268},{"className":1267},[1150],[1269],{"type":49,"tag":84,"props":1270,"children":1272},{"className":1271},[1155],[1273,1276,1278,1282],{"type":49,"tag":1158,"props":1274,"children":1275},{"disabled":896,"type":1160},[],{"type":55,"value":1277}," ",{"type":49,"tag":74,"props":1279,"children":1280},{},[1281],{"type":55,"value":256},{"type":55,"value":1283},": Dividing prices by 100 when displaying (prices are stored as-is: $49.99 = 49.99, NOT in cents)",{"type":49,"tag":58,"props":1285,"children":1286},{},[1287],{"type":49,"tag":74,"props":1288,"children":1289},{},[1290],{"type":55,"value":1291},"Error Handling:",{"type":49,"tag":80,"props":1293,"children":1295},{"className":1294},[1150],[1296,1305,1314],{"type":49,"tag":84,"props":1297,"children":1299},{"className":1298},[1155],[1300,1303],{"type":49,"tag":1158,"props":1301,"children":1302},{"disabled":896,"type":1160},[],{"type":55,"value":1304}," Not implementing onError callbacks",{"type":49,"tag":84,"props":1306,"children":1308},{"className":1307},[1155],[1309,1312],{"type":49,"tag":1158,"props":1310,"children":1311},{"disabled":896,"type":1160},[],{"type":55,"value":1313}," Not showing error messages to users",{"type":49,"tag":84,"props":1315,"children":1317},{"className":1316},[1155],[1318,1321],{"type":49,"tag":1158,"props":1319,"children":1320},{"disabled":896,"type":1160},[],{"type":55,"value":1322}," Not handling network failures gracefully",{"type":49,"tag":64,"props":1324,"children":1326},{"id":1325},"how-to-use",[1327],{"type":55,"value":1328},"How to Use",{"type":49,"tag":58,"props":1330,"children":1331},{},[1332],{"type":49,"tag":74,"props":1333,"children":1334},{},[1335],{"type":55,"value":1336},"For detailed patterns and examples, load reference file:",{"type":49,"tag":674,"props":1338,"children":1342},{"className":1339,"code":1341,"language":55},[1340],"language-text","references\u002Ffrontend-integration.md - SDK usage, React Query patterns, API integration\n",[1343],{"type":49,"tag":157,"props":1344,"children":1345},{"__ignoreMap":679},[1346],{"type":55,"value":1341},{"type":49,"tag":58,"props":1348,"children":1349},{},[1350],{"type":55,"value":1351},"The reference file contains:",{"type":49,"tag":80,"props":1353,"children":1354},{},[1355,1360,1365,1370,1375,1380],{"type":49,"tag":84,"props":1356,"children":1357},{},[1358],{"type":55,"value":1359},"Step-by-step SDK integration patterns",{"type":49,"tag":84,"props":1361,"children":1362},{},[1363],{"type":55,"value":1364},"Complete React Query examples",{"type":49,"tag":84,"props":1366,"children":1367},{},[1368],{"type":55,"value":1369},"Correct vs incorrect code examples",{"type":49,"tag":84,"props":1371,"children":1372},{},[1373],{"type":55,"value":1374},"Query key best practices",{"type":49,"tag":84,"props":1376,"children":1377},{},[1378],{"type":55,"value":1379},"Optimistic update patterns",{"type":49,"tag":84,"props":1381,"children":1382},{},[1383],{"type":55,"value":1384},"Error handling strategies",{"type":49,"tag":64,"props":1386,"children":1388},{"id":1387},"when-to-use-medusadocs-mcp-server",[1389],{"type":55,"value":1390},"When to Use MedusaDocs MCP Server",{"type":49,"tag":58,"props":1392,"children":1393},{},[1394],{"type":49,"tag":74,"props":1395,"children":1396},{},[1397],{"type":55,"value":1398},"Use this skill for (PRIMARY SOURCE):",{"type":49,"tag":80,"props":1400,"children":1401},{},[1402,1407,1412,1417],{"type":49,"tag":84,"props":1403,"children":1404},{},[1405],{"type":55,"value":1406},"How to call custom API routes from storefront",{"type":49,"tag":84,"props":1408,"children":1409},{},[1410],{"type":55,"value":1411},"SDK usage patterns (sdk.client.fetch)",{"type":49,"tag":84,"props":1413,"children":1414},{},[1415],{"type":55,"value":1416},"React Query integration patterns",{"type":49,"tag":84,"props":1418,"children":1419},{},[1420],{"type":55,"value":1421},"Common mistakes and anti-patterns",{"type":49,"tag":58,"props":1423,"children":1424},{},[1425],{"type":49,"tag":74,"props":1426,"children":1427},{},[1428],{"type":55,"value":1429},"Use MedusaDocs MCP server for (SECONDARY SOURCE):",{"type":49,"tag":80,"props":1431,"children":1432},{},[1433,1445,1450],{"type":49,"tag":84,"props":1434,"children":1435},{},[1436,1438,1444],{"type":55,"value":1437},"Built-in SDK methods (sdk.admin.",{"type":49,"tag":1439,"props":1440,"children":1441},"em",{},[1442],{"type":55,"value":1443},", sdk.store.",{"type":55,"value":407},{"type":49,"tag":84,"props":1446,"children":1447},{},[1448],{"type":55,"value":1449},"Official Medusa SDK API reference",{"type":49,"tag":84,"props":1451,"children":1452},{},[1453],{"type":55,"value":1454},"Framework-specific configuration options",{"type":49,"tag":58,"props":1456,"children":1457},{},[1458],{"type":49,"tag":74,"props":1459,"children":1460},{},[1461],{"type":55,"value":1462},"Why skills come first:",{"type":49,"tag":80,"props":1464,"children":1465},{},[1466,1471,1476],{"type":49,"tag":84,"props":1467,"children":1468},{},[1469],{"type":55,"value":1470},"Skills contain critical patterns like \"don't use JSON.stringify\" that MCP doesn't emphasize",{"type":49,"tag":84,"props":1472,"children":1473},{},[1474],{"type":55,"value":1475},"Skills show correct vs incorrect patterns; MCP shows what's possible",{"type":49,"tag":84,"props":1477,"children":1478},{},[1479],{"type":55,"value":1480},"Planning requires understanding patterns, not just API reference",{"type":49,"tag":64,"props":1482,"children":1484},{"id":1483},"integration-with-backend",[1485],{"type":55,"value":1486},"Integration with Backend",{"type":49,"tag":58,"props":1488,"children":1489},{},[1490],{"type":49,"tag":74,"props":1491,"children":1492},{},[1493],{"type":55,"value":1494},"⚠️ CRITICAL: ALWAYS use the Medusa JS SDK - NEVER use regular fetch()",{"type":49,"tag":58,"props":1496,"children":1497},{},[1498],{"type":55,"value":1499},"When building features that span backend and frontend:",{"type":49,"tag":1501,"props":1502,"children":1503},"ol",{},[1504,1514,1524],{"type":49,"tag":84,"props":1505,"children":1506},{},[1507,1512],{"type":49,"tag":74,"props":1508,"children":1509},{},[1510],{"type":55,"value":1511},"Backend (building-with-medusa skill):",{"type":55,"value":1513}," Module → Workflow → API Route",{"type":49,"tag":84,"props":1515,"children":1516},{},[1517,1522],{"type":49,"tag":74,"props":1518,"children":1519},{},[1520],{"type":55,"value":1521},"Storefront (this skill):",{"type":55,"value":1523}," SDK → React Query → UI Components",{"type":49,"tag":84,"props":1525,"children":1526},{},[1527,1532],{"type":49,"tag":74,"props":1528,"children":1529},{},[1530],{"type":55,"value":1531},"Connection:",{"type":49,"tag":80,"props":1533,"children":1534},{},[1535,1546,1557],{"type":49,"tag":84,"props":1536,"children":1537},{},[1538,1540,1545],{"type":55,"value":1539},"Built-in endpoints: Use existing SDK methods (",{"type":49,"tag":157,"props":1541,"children":1543},{"className":1542},[],[1544],{"type":55,"value":397},{"type":55,"value":407},{"type":49,"tag":84,"props":1547,"children":1548},{},[1549,1551],{"type":55,"value":1550},"Custom API routes: Use ",{"type":49,"tag":157,"props":1552,"children":1554},{"className":1553},[],[1555],{"type":55,"value":1556},"sdk.client.fetch(\"\u002Fstore\u002Fmy-route\")",{"type":49,"tag":84,"props":1558,"children":1559},{},[1560,1565],{"type":49,"tag":74,"props":1561,"children":1562},{},[1563],{"type":55,"value":1564},"NEVER use regular fetch()",{"type":55,"value":1566}," - missing publishable API key causes errors",{"type":49,"tag":58,"props":1568,"children":1569},{},[1570],{"type":49,"tag":74,"props":1571,"children":1572},{},[1573],{"type":55,"value":1574},"Why the SDK is required:",{"type":49,"tag":80,"props":1576,"children":1577},{},[1578,1591,1604,1609],{"type":49,"tag":84,"props":1579,"children":1580},{},[1581,1583,1589],{"type":55,"value":1582},"Store routes need ",{"type":49,"tag":157,"props":1584,"children":1586},{"className":1585},[],[1587],{"type":55,"value":1588},"x-publishable-api-key",{"type":55,"value":1590}," header",{"type":49,"tag":84,"props":1592,"children":1593},{},[1594,1596,1602],{"type":55,"value":1595},"Admin routes need ",{"type":49,"tag":157,"props":1597,"children":1599},{"className":1598},[],[1600],{"type":55,"value":1601},"Authorization",{"type":55,"value":1603}," and session headers",{"type":49,"tag":84,"props":1605,"children":1606},{},[1607],{"type":55,"value":1608},"SDK handles all required headers automatically",{"type":49,"tag":84,"props":1610,"children":1611},{},[1612],{"type":55,"value":1613},"Regular fetch() without headers → authentication\u002Fauthorization errors",{"type":49,"tag":58,"props":1615,"children":1616},{},[1617,1619,1625],{"type":55,"value":1618},"See ",{"type":49,"tag":157,"props":1620,"children":1622},{"className":1621},[],[1623],{"type":55,"value":1624},"building-with-medusa",{"type":55,"value":1626}," for backend API route patterns.",{"type":49,"tag":1628,"props":1629,"children":1630},"style",{},[1631],{"type":55,"value":1632},"html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"items":1634,"total":1092},[1635,1648,1656,1670,1682,1697,1707],{"slug":1636,"name":1636,"fn":1637,"description":1638,"org":1639,"tags":1640,"stars":27,"repoUrl":28,"updatedAt":1647},"building-admin-dashboard-customizations","customize Medusa Admin dashboard UI","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.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1641,1642,1643,1644],{"name":19,"slug":20,"type":16},{"name":25,"slug":26,"type":16},{"name":9,"slug":8,"type":16},{"name":1645,"slug":1646,"type":16},"UI Components","ui-components","2026-04-06T18:29:57.203659",{"slug":4,"name":4,"fn":5,"description":6,"org":1649,"tags":1650,"stars":27,"repoUrl":28,"updatedAt":29},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1651,1652,1653,1654,1655],{"name":19,"slug":20,"type":16},{"name":22,"slug":23,"type":16},{"name":25,"slug":26,"type":16},{"name":9,"slug":8,"type":16},{"name":14,"slug":15,"type":16},{"slug":1624,"name":1624,"fn":1657,"description":1658,"org":1659,"tags":1660,"stars":27,"repoUrl":28,"updatedAt":1669},"implement Medusa backend features","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.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1661,1664,1667,1668],{"name":1662,"slug":1663,"type":16},"Backend","backend",{"name":1665,"slug":1666,"type":16},"Data Modeling","data-modeling",{"name":19,"slug":20,"type":16},{"name":9,"slug":8,"type":16},"2026-04-06T18:29:54.652389",{"slug":1671,"name":1671,"fn":1672,"description":1673,"org":1674,"tags":1675,"stars":27,"repoUrl":28,"updatedAt":1681},"creating-agents-in-medusa","build admin-facing AI agents in Medusa","Use when building an internal admin-facing AI agent in a Medusa project. These agents are operated by merchants and store operators — not customers. Covers data models, module service, agent runtime (tools, system prompt, streamText), streaming API routes (NDJSON), and admin UI chat extensions. Load for any internal agent type: store operations assistant, product audit, cohort analysis, customer service tooling for support staff, etc. Do NOT use for customer-facing agents (storefront chatbots, buyer-side assistants).",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1676,1679,1680],{"name":1677,"slug":1678,"type":16},"Agents","agents",{"name":1662,"slug":1663,"type":16},{"name":9,"slug":8,"type":16},"2026-07-14T05:42:09.367168",{"slug":1683,"name":1683,"fn":1684,"description":1685,"org":1686,"tags":1687,"stars":27,"repoUrl":28,"updatedAt":1696},"db-generate","generate database migrations for Medusa modules","Generate database migrations for a Medusa module",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1688,1689,1692,1693],{"name":1662,"slug":1663,"type":16},{"name":1690,"slug":1691,"type":16},"Database","database",{"name":9,"slug":8,"type":16},{"name":1694,"slug":1695,"type":16},"Migration","migration","2026-04-06T18:29:53.415671",{"slug":1698,"name":1698,"fn":1699,"description":1700,"org":1701,"tags":1702,"stars":27,"repoUrl":28,"updatedAt":1706},"db-migrate","run database migrations in Medusa","Run database migrations in Medusa",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1703,1704,1705],{"name":1690,"slug":1691,"type":16},{"name":9,"slug":8,"type":16},{"name":1694,"slug":1695,"type":16},"2026-04-06T18:29:52.187377",{"slug":1708,"name":1708,"fn":1709,"description":1710,"org":1711,"tags":1712,"stars":27,"repoUrl":28,"updatedAt":1719},"learning-medusa","guide Medusa development learning","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.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1713,1714,1715,1716],{"name":1662,"slug":1663,"type":16},{"name":19,"slug":20,"type":16},{"name":9,"slug":8,"type":16},{"name":1717,"slug":1718,"type":16},"Templates","templates","2026-04-06T18:29:58.461689",{"items":1721,"total":1092},[1722,1729,1737,1744,1750,1757,1763,1770,1787,1799,1812,1825],{"slug":1636,"name":1636,"fn":1637,"description":1638,"org":1723,"tags":1724,"stars":27,"repoUrl":28,"updatedAt":1647},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1725,1726,1727,1728],{"name":19,"slug":20,"type":16},{"name":25,"slug":26,"type":16},{"name":9,"slug":8,"type":16},{"name":1645,"slug":1646,"type":16},{"slug":4,"name":4,"fn":5,"description":6,"org":1730,"tags":1731,"stars":27,"repoUrl":28,"updatedAt":29},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1732,1733,1734,1735,1736],{"name":19,"slug":20,"type":16},{"name":22,"slug":23,"type":16},{"name":25,"slug":26,"type":16},{"name":9,"slug":8,"type":16},{"name":14,"slug":15,"type":16},{"slug":1624,"name":1624,"fn":1657,"description":1658,"org":1738,"tags":1739,"stars":27,"repoUrl":28,"updatedAt":1669},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1740,1741,1742,1743],{"name":1662,"slug":1663,"type":16},{"name":1665,"slug":1666,"type":16},{"name":19,"slug":20,"type":16},{"name":9,"slug":8,"type":16},{"slug":1671,"name":1671,"fn":1672,"description":1673,"org":1745,"tags":1746,"stars":27,"repoUrl":28,"updatedAt":1681},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1747,1748,1749],{"name":1677,"slug":1678,"type":16},{"name":1662,"slug":1663,"type":16},{"name":9,"slug":8,"type":16},{"slug":1683,"name":1683,"fn":1684,"description":1685,"org":1751,"tags":1752,"stars":27,"repoUrl":28,"updatedAt":1696},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1753,1754,1755,1756],{"name":1662,"slug":1663,"type":16},{"name":1690,"slug":1691,"type":16},{"name":9,"slug":8,"type":16},{"name":1694,"slug":1695,"type":16},{"slug":1698,"name":1698,"fn":1699,"description":1700,"org":1758,"tags":1759,"stars":27,"repoUrl":28,"updatedAt":1706},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1760,1761,1762],{"name":1690,"slug":1691,"type":16},{"name":9,"slug":8,"type":16},{"name":1694,"slug":1695,"type":16},{"slug":1708,"name":1708,"fn":1709,"description":1710,"org":1764,"tags":1765,"stars":27,"repoUrl":28,"updatedAt":1719},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1766,1767,1768,1769],{"name":1662,"slug":1663,"type":16},{"name":19,"slug":20,"type":16},{"name":9,"slug":8,"type":16},{"name":1717,"slug":1718,"type":16},{"slug":1771,"name":1771,"fn":1772,"description":1773,"org":1774,"tags":1775,"stars":27,"repoUrl":28,"updatedAt":1786},"mcloud-deployments","manage Medusa Cloud deployments","Execute mcloud deployments commands to list deployments, retrieve deployment details, and fetch build logs. Use when listing deployments, checking deployment status, or reading build output for debugging build failures.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1776,1779,1782,1783],{"name":1777,"slug":1778,"type":16},"Deployment","deployment",{"name":1780,"slug":1781,"type":16},"Logs","logs",{"name":9,"slug":8,"type":16},{"name":1784,"slug":1785,"type":16},"Observability","observability","2026-05-09T05:40:51.727369",{"slug":1788,"name":1788,"fn":1789,"description":1790,"org":1791,"tags":1792,"stars":27,"repoUrl":28,"updatedAt":1798},"mcloud-environments","manage Medusa Cloud environments","Execute mcloud environments commands to list, get, create, delete, redeploy, or trigger builds for Cloud environments. Use when managing environment lifecycle, redeploying after variable changes, or starting new builds from source.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1793,1794,1795],{"name":1777,"slug":1778,"type":16},{"name":9,"slug":8,"type":16},{"name":1796,"slug":1797,"type":16},"Operations","operations","2026-07-17T05:31:36.384292",{"slug":1800,"name":1800,"fn":1801,"description":1802,"org":1803,"tags":1804,"stars":27,"repoUrl":28,"updatedAt":1811},"mcloud-local","reproduce Cloud builds locally","Execute mcloud local build to reproduce a Cloud build on the local machine. Use when debugging a build-failed deployment without pushing to the tracked branch, iterating on a build fix, or testing build-variable changes locally. Requires Docker and must run inside the project's Git repo.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1805,1808,1809,1810],{"name":1806,"slug":1807,"type":16},"Debugging","debugging",{"name":1777,"slug":1778,"type":16},{"name":22,"slug":23,"type":16},{"name":9,"slug":8,"type":16},"2026-07-17T06:05:07.199529",{"slug":1813,"name":1813,"fn":1814,"description":1815,"org":1816,"tags":1817,"stars":27,"repoUrl":28,"updatedAt":1824},"mcloud-logs","fetch and stream runtime cloud logs","Execute mcloud logs to fetch and stream runtime logs for Cloud environments. Use when reading backend or storefront logs, filtering by time range, searching for errors, or scoping logs to a specific deployment.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1818,1821,1822,1823],{"name":1819,"slug":1820,"type":16},"Cloud","cloud",{"name":1780,"slug":1781,"type":16},{"name":9,"slug":8,"type":16},{"name":1784,"slug":1785,"type":16},"2026-05-09T05:40:46.707854",{"slug":1826,"name":1826,"fn":1827,"description":1828,"org":1829,"tags":1830,"stars":27,"repoUrl":28,"updatedAt":1833},"mcloud-organizations","manage Medusa Cloud organizations","Execute mcloud organizations commands to list or get Cloud organizations. Use when discovering organizations, resolving organization IDs by name, or retrieving organization details including members and subscription.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[1831,1832],{"name":9,"slug":8,"type":16},{"name":1796,"slug":1797,"type":16},"2026-05-09T05:40:54.327722"]