Medusa Storefront

Medusa v2 Storefront with Next.js

Before writing code

Fetch live docs:

1. Fetch https://docs.medusajs.com/resources/storefront-development for storefront overview
2. Web-search site:docs.medusajs.com nextjs starter storefront for starter template
3. Web-search site:docs.medusajs.com JS SDK client setup for Medusa SDK configuration
4. Web-search site:docs.medusajs.com storefront API reference for Store API endpoints
5. 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:

Next.js Starter Structure

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

Fetch live docs for the complete SDK namespace list and method signatures.

Server Components vs Client Components

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

Cart ID is typically stored in a cookie or localStorage for persistence across sessions.

Checkout Flow

Customer Authentication

// 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

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.