# building-storefronts

A skill for building Medusa storefronts: it tells the agent how to call APIs through the SDK and React Query without breaking requests.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 4200 installs · ★ 235
- Author: medusajs
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/medusajs/medusa-agent-skills/tree/HEAD/plugins/medusa-dev/skills/building-storefronts/SKILL.md
- Updated: 2026-10-21
- HTML: https://affpapa.org/en/nevibecode/skills/building-storefronts

## What it does

This skill covers frontend work on a Medusa store. It holds rules for the Medusa JS SDK, React Query patterns for fetching and mutating data, and calls to custom API routes. The agent loads it on its own when you plan or write storefront code.

The core rule: every request goes through the SDK, plain `fetch()` is out. The SDK adds the headers itself — publishable API key for store routes, auth for admin. Bodies are passed as plain objects, and `JSON.stringify()` breaks the request by double-serializing it. Built-in endpoints use existing methods like `sdk.store.product.list()`, custom routes use `sdk.client.fetch()`.

Prices get their own warning: values arrive as-is, 49.99 means 49.99, so dividing by 100 is wrong. That mistake shows up often and turns a price into pocket change. Before writing integration code the skill requires loading `references/frontend-integration.md` for the full examples. A companion skill, `building-with-medusa`, handles the backend routes the storefront calls.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add medusajs/medusa-agent-skills --skill building-storefronts -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/building-storefronts/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/building-storefronts/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add medusajs/medusa-agent-skills --skill building-storefronts -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/building-storefronts/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add medusajs/medusa-agent-skills --skill building-storefronts -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/building-storefronts/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install medusajs/medusa-agent-skills building-storefronts
```

2. **Manually: put the files in place**
- File: `.github/skills/building-storefronts/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add medusajs/medusa-agent-skills --skill building-storefronts -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/medusajs/medusa-agent-skills --path plugins/medusa-dev/skills/building-storefronts
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/building-storefronts/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add medusajs/medusa-agent-skills --skill building-storefronts -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/medusajs/medusa-agent-skills/tree/HEAD/plugins/medusa-dev/skills/building-storefronts/SKILL.md

## When to use it
- call a custom Medusa API route from the storefront
- wire the Medusa JS SDK into a frontend app
- set up data fetching with React Query
- build a mutation with optimistic update and rollback
- fix a price that was divided by 100

## Example prompts
- Help me call the custom /store/reviews route from my Medusa storefront using the SDK
- Set up useQuery for the product list and useMutation for adding a review
- Review my Medusa storefront code for SDK mistakes

## Similar
- [storefront-builder](https://affpapa.org/en/nevibecode/skills/storefront-builder.md) — skill · 384 installs
- [shopify-storefront-graphql](https://affpapa.org/en/nevibecode/skills/shopify-storefront-graphql.md) — skill · 1 install
- [wix-headless](https://affpapa.org/en/nevibecode/skills/wix-headless.md) — skill · 338 installs
- [building-livekit-agents](https://affpapa.org/en/nevibecode/skills/building-livekit-agents.md) — skill · 419 installs
- [building-emdash-site](https://affpapa.org/en/nevibecode/skills/building-emdash-site.md) — skill · 756 installs
- [expo-data-fetching](https://affpapa.org/en/nevibecode/skills/expo-data-fetching.md) — skill · 27500 installs

From the same set: [medusajs/medusa-agent-skills](https://affpapa.org/en/nevibecode/by/medusajs/medusa-agent-skills.md) — 12 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md