Medusa v2 Storefront with Next.js
Before writing code
Fetch live docs:
- Fetch
https://docs.medusajs.com/resources/storefront-development for storefront overview
- Web-search
site:docs.medusajs.com nextjs starter storefront for starter template
- Web-search
site:docs.medusajs.com JS SDK client setup for Medusa SDK configuration
- Web-search
site:docs.medusajs.com storefront API reference for Store API endpoints
- Web-search
site:github.com medusajs nextjs-starter-medusa for latest starter source
Storefront Architecture
Medusa v2 storefronts are headless -- they consume the Store API over HTTP:
| Layer |
Component |
| Frontend |
Next.js App (SSR/RSC) |
| HTTP Client |
Medusa JS SDK |
| Backend |
Medusa Backend (/store/* API routes) |
| Storage |
PostgreSQL / Redis |
Next.js Starter Structure
| Directory |
Key Files |
app/ |
layout.tsx, page.tsx (homepage) |
app/(main)/products/ |
page.tsx (listing), [handle]/page.tsx (detail) |
app/(main)/collections/ |
[handle]/page.tsx (collection) |
app/(main)/cart/, app/(main)/checkout/ |
Cart page, checkout flow |
app/(auth)/, app/account/ |
Login/register, customer dashboard |
lib/ |
sdk.ts (Medusa client), data/ (fetching), util/ |
components/ |
products/, cart/, checkout/, layout/ |
| Root |
next.config.js, .env.local |
JS SDK Client Setup
SDK Installation
The Medusa JS SDK provides typed access to the Store API:
// lib/sdk.ts — Fetch live docs for Medusa SDK initialization
import Medusa from "@medusajs/js-sdk"
export const sdk = new Medusa({
baseUrl: process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL!,
// Fetch live docs for publishableKey and other options
})
Environment Variables
NEXT_PUBLIC_MEDUSA_BACKEND_URL=http://localhost:9000
NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_...
The publishable API key is required for Store API requests and scopes them to a specific sales channel.
Key Store API Domains
| Domain |
SDK Namespace |
Key Operations |
| Products |
sdk.store.product |
List, retrieve by handle |
| Collections |
sdk.store.collection |
List, retrieve |
| Categories |
sdk.store.category |
List, tree |
| Cart |
sdk.store.cart |
Create, add items, update |
| Checkout |
sdk.store.cart |
Add shipping, complete |
| Customer |
sdk.store.customer |
Register, login, profile |
| Orders |
sdk.store.order |
List customer orders |
| Regions |
sdk.store.region |
List regions and currencies |
| Shipping |
sdk.store.fulfillment |
List shipping options |
Fetch live docs for the complete SDK namespace list and method signatures.
Server Components vs Client Components
| Pattern |
Use For |
| Server Component (RSC) |
Product listing, product detail, static content |
| Client Component |
Cart interactions, checkout form, quantity selectors |
| Server Action |
Cart mutations, checkout submission |
Data Fetching in Server Components
// app/(main)/products/[handle]/page.tsx
// Fetch live docs for SDK method signatures
export default async function ProductPage({ params }) {
const { product } = await sdk.store.product.retrieve(params.handle)
return <ProductTemplate product={product} />
}
Cart Flow
| Step |
Action |
SDK Method |
| 1. Create cart |
On first add-to-cart |
sdk.store.cart.create() |
| 2. Add line item |
User adds product |
sdk.store.cart.addLineItem() |
| 3. Update quantity |
User changes qty |
sdk.store.cart.updateLineItem() |
| 4. Remove item |
User removes product |
sdk.store.cart.removeLineItem() |
| 5. Set region |
Auto or user selection |
sdk.store.cart.update() |
Cart ID is typically stored in a cookie or localStorage for persistence across sessions.
Checkout Flow
| Step |
Required Data |
SDK Call |
| 1. Address |
Shipping + billing address |
sdk.store.cart.update() |
| 2. Shipping |
Selected shipping option |
sdk.store.cart.addShippingMethod() |
| 3. Payment |
Payment provider session |
sdk.store.cart.initiatePaymentSession() |
| 4. Complete |
Confirmation |
sdk.store.cart.complete() |
Customer Authentication
| Flow |
Description |
| Registration |
Create customer account via Store API |
| Login |
Authenticate and receive session token |
| Session |
Token stored in cookie, sent with requests |
| Profile |
Update customer info, addresses |
| Orders |
View past orders linked to customer |
// Fetch live docs for customer auth SDK methods
await sdk.auth.login("customer", "emailpass", {
email: "user@example.com",
password: "password",
})
Region and Currency Handling
- Medusa supports multiple regions with different currencies
- Storefront should detect or let the user select a region
- All product prices are region-aware
- Cart is tied to a region which determines currency and tax rules
Performance Considerations
| Technique |
Implementation |
| Static Generation (SSG) |
Use generateStaticParams for product pages |
| ISR |
Revalidate product pages periodically |
| Streaming |
Use Suspense boundaries for slow data |
| Image optimization |
Use Next.js <Image> with Medusa image URLs |
| Prefetching |
Use <Link> for product navigation |
Best Practices
- Use Server Components for data fetching -- minimize client-side JavaScript
- Store the cart ID in a cookie for cross-tab and SSR access
- Use the publishable API key to scope requests to the correct sales channel
- Handle region/currency at the layout level, not per-page
- Implement optimistic UI updates for cart operations to improve perceived performance
- Use
generateStaticParams for product and collection pages for SEO and speed
- Keep checkout as a linear flow -- do not allow skipping steps
Fetch the Medusa storefront documentation and Next.js starter source for exact SDK method signatures, component patterns, and checkout flow details before implementing.
1---2name: medusa-storefront3description: Build Medusa v2 storefronts with Next.js 15 — App Router, JS SDK client setup, Tanstack Query, server components, product pages, cart, and checkout flow. Use when developing headless storefronts.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/medusa-storefront7---89# Medusa v2 Storefront with Next.js1011## Before writing code1213**Fetch live docs**:141. Fetch `https://docs.medusajs.com/resources/storefront-development` for storefront overview152. Web-search `site:docs.medusajs.com nextjs starter storefront` for starter template163. Web-search `site:docs.medusajs.com JS SDK client setup` for Medusa SDK configuration174. Web-search `site:docs.medusajs.com storefront API reference` for Store API endpoints185. Web-search `site:github.com medusajs nextjs-starter-medusa` for latest starter source1920## Storefront Architecture2122Medusa v2 storefronts are headless -- they consume the Store API over HTTP:2324| Layer | Component |25|-------|-----------|26| Frontend | Next.js App (SSR/RSC) |27| HTTP Client | Medusa JS SDK |28| Backend | Medusa Backend (`/store/*` API routes) |29| Storage | PostgreSQL / Redis |3031## Next.js Starter Structure3233| Directory | Key Files |34|-----------|-----------|35| `app/` | `layout.tsx`, `page.tsx` (homepage) |36| `app/(main)/products/` | `page.tsx` (listing), `[handle]/page.tsx` (detail) |37| `app/(main)/collections/` | `[handle]/page.tsx` (collection) |38| `app/(main)/cart/`, `app/(main)/checkout/` | Cart page, checkout flow |39| `app/(auth)/`, `app/account/` | Login/register, customer dashboard |40| `lib/` | `sdk.ts` (Medusa client), `data/` (fetching), `util/` |41| `components/` | `products/`, `cart/`, `checkout/`, `layout/` |42| Root | `next.config.js`, `.env.local` |4344## JS SDK Client Setup4546### SDK Installation4748The Medusa JS SDK provides typed access to the Store API:4950```typescript51// lib/sdk.ts — Fetch live docs for Medusa SDK initialization52import Medusa from "@medusajs/js-sdk"5354export const sdk = new Medusa({55 baseUrl: process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL!,56 // Fetch live docs for publishableKey and other options57})58```5960### Environment Variables6162```63NEXT_PUBLIC_MEDUSA_BACKEND_URL=http://localhost:900064NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_...65```6667The publishable API key is required for Store API requests and scopes them to a specific sales channel.6869## Key Store API Domains7071| Domain | SDK Namespace | Key Operations |72|--------|--------------|----------------|73| Products | `sdk.store.product` | List, retrieve by handle |74| Collections | `sdk.store.collection` | List, retrieve |75| Categories | `sdk.store.category` | List, tree |76| Cart | `sdk.store.cart` | Create, add items, update |77| Checkout | `sdk.store.cart` | Add shipping, complete |78| Customer | `sdk.store.customer` | Register, login, profile |79| Orders | `sdk.store.order` | List customer orders |80| Regions | `sdk.store.region` | List regions and currencies |81| Shipping | `sdk.store.fulfillment` | List shipping options |8283> **Fetch live docs** for the complete SDK namespace list and method signatures.8485## Server Components vs Client Components8687| Pattern | Use For |88|---------|---------|89| Server Component (RSC) | Product listing, product detail, static content |90| Client Component | Cart interactions, checkout form, quantity selectors |91| Server Action | Cart mutations, checkout submission |9293### Data Fetching in Server Components9495```typescript96// app/(main)/products/[handle]/page.tsx97// Fetch live docs for SDK method signatures98export default async function ProductPage({ params }) {99 const { product } = await sdk.store.product.retrieve(params.handle)100 return <ProductTemplate product={product} />101}102```103104## Cart Flow105106| Step | Action | SDK Method |107|------|--------|-----------|108| 1. Create cart | On first add-to-cart | `sdk.store.cart.create()` |109| 2. Add line item | User adds product | `sdk.store.cart.addLineItem()` |110| 3. Update quantity | User changes qty | `sdk.store.cart.updateLineItem()` |111| 4. Remove item | User removes product | `sdk.store.cart.removeLineItem()` |112| 5. Set region | Auto or user selection | `sdk.store.cart.update()` |113114Cart ID is typically stored in a cookie or localStorage for persistence across sessions.115116## Checkout Flow117118| Step | Required Data | SDK Call |119|------|--------------|---------|120| 1. Address | Shipping + billing address | `sdk.store.cart.update()` |121| 2. Shipping | Selected shipping option | `sdk.store.cart.addShippingMethod()` |122| 3. Payment | Payment provider session | `sdk.store.cart.initiatePaymentSession()` |123| 4. Complete | Confirmation | `sdk.store.cart.complete()` |124125## Customer Authentication126127| Flow | Description |128|------|-------------|129| Registration | Create customer account via Store API |130| Login | Authenticate and receive session token |131| Session | Token stored in cookie, sent with requests |132| Profile | Update customer info, addresses |133| Orders | View past orders linked to customer |134135```typescript136// Fetch live docs for customer auth SDK methods137await sdk.auth.login("customer", "emailpass", {138 email: "user@example.com",139 password: "password",140})141```142143## Region and Currency Handling144145- Medusa supports multiple regions with different currencies146- Storefront should detect or let the user select a region147- All product prices are region-aware148- Cart is tied to a region which determines currency and tax rules149150## Performance Considerations151152| Technique | Implementation |153|-----------|---------------|154| Static Generation (SSG) | Use `generateStaticParams` for product pages |155| ISR | Revalidate product pages periodically |156| Streaming | Use Suspense boundaries for slow data |157| Image optimization | Use Next.js `<Image>` with Medusa image URLs |158| Prefetching | Use `<Link>` for product navigation |159160## Best Practices161162- Use Server Components for data fetching -- minimize client-side JavaScript163- Store the cart ID in a cookie for cross-tab and SSR access164- Use the publishable API key to scope requests to the correct sales channel165- Handle region/currency at the layout level, not per-page166- Implement optimistic UI updates for cart operations to improve perceived performance167- Use `generateStaticParams` for product and collection pages for SEO and speed168- Keep checkout as a linear flow -- do not allow skipping steps169170Fetch the Medusa storefront documentation and Next.js starter source for exact SDK method signatures, component patterns, and checkout flow details before implementing.