nextjs-patterns

Next.js 15 Storefront Patterns for Medusa v2

Before writing code

Fetch live docs:

1. Web-search site:docs.medusajs.com storefront nextjs for Medusa storefront guides
2. Fetch https://docs.medusajs.com/resources/references/js-sdk for JS SDK method reference
3. Web-search site:nextjs.org docs app router for latest Next.js 15 App Router conventions
4. Web-search site:docs.medusajs.com nextjs starter storefront for starter template patterns
5. Web-search site:docs.medusajs.com publishable api key storefront for API authentication setup

App Router Conventions

Directory Structure

src/app/
├── layout.tsx        — Root layout (providers, SDK)
├── page.tsx          — Home page
├── (main)/products/  — Product listing + [handle]/
├── (main)/cart/      — Cart, checkout, account
└── lib/medusa.ts     — SDK client initialization

Key App Router Concepts

Concept	File Convention	Purpose in Medusa Storefront
Layout	layout.tsx	Wrap pages with providers, header, footer
Page	page.tsx	Route entry point (server component default)
Loading	loading.tsx	Streaming fallback UI
Error	error.tsx	Error boundary per route segment
Not Found	not-found.tsx	404 page for invalid product handles, etc.
Route Groups	(group)/	Organize without affecting URL
Dynamic Routes	[param]/	Product handles, category slugs
Parallel Routes	@slot/	Simultaneous layout regions

Server vs Client Components

Decision Matrix

Criterion	Server Component	Client Component
Data fetching	Fetch from Medusa API directly	Use Tanstack Query hooks
SEO	Full HTML rendered on server	Not indexed by crawlers
Interactivity	No event handlers	onClick, onChange, etc.
State	No useState/useEffect	Full React hooks
Examples	Product listing, product detail, categories	Cart actions, quantity selector, search
Directive	None (default)	"use client" at top

Component Split Pattern

ProductPage (server)
├── ProductInfo (server)      — Title, description, price
├── ProductImages (server)    — Image gallery markup
├── AddToCart (client)        — "use client", quantity, button
└── RelatedProducts (server)  — Fetched server-side

Medusa JS SDK Integration

SDK Initialization and Configuration

Option	Purpose	Example Value
baseUrl	Medusa server URL	http://localhost:9000
publishableKey	Store API authentication	From admin dashboard
auth.type	Authentication strategy	"session" or "jwt"

Common SDK Methods

Domain	Method Pattern	Component Type
Products	sdk.store.product.list()	Server (listing)
Products	sdk.store.product.retrieve(id)	Server (detail)
Cart	sdk.store.cart.create()	Client (interaction)
Cart	sdk.store.cart.addLineItem()	Client (interaction)
Cart	sdk.store.cart.update()	Client (interaction)
Checkout	sdk.store.cart.addShippingMethod()	Client (checkout flow)
Customer	sdk.auth.login()	Client (auth form)
Customer	sdk.store.customer.retrieve()	Server or Client
Regions	sdk.store.region.list()	Server (layout)
Collections	sdk.store.collection.list()	Server (navigation)

Data Fetching Patterns

Server Component Fetching

Call the Medusa SDK directly in server components — no hooks needed:

// Fetch live docs for server-side SDK
// usage and async component patterns

Pattern	Use Case
Direct await sdk.store.*	Server components with async data
generateMetadata()	Dynamic SEO metadata from product data
generateStaticParams()	ISR/SSG for product and category pages

Client Component Fetching (Tanstack Query)

Hook / Concern	Purpose
useQuery	Read data with caching and automatic refetch
useMutation	Write operations (add to cart, login)
useQueryClient	Invalidate cache after mutations
Query keys	Use consistent keys like ["cart", cartId]
Optimistic updates	Update cart UI immediately, rollback on error
Prefetching	Prefetch product data on hover for navigation

Caching Strategies

Next.js Caching Layers

Layer	Scope	Medusa Use Case
Request Memoization	Per-request dedup	Multiple components fetching same product
Data Cache	Cross-request	Product catalog data (revalidate periodically)
Full Route Cache	Entire page	Static product pages (ISR)
Router Cache	Client-side	Navigation between cached pages

Revalidation Patterns

Strategy	Method	Use Case
Time-based	revalidate: 60 (seconds)	Product listings, category pages
On-demand	revalidatePath() / revalidateTag()	After admin product update
No cache	cache: "no-store"	Cart, checkout, customer data

Cache Configuration per Data Type

Data Type	Cache Strategy	Reasoning
Products	revalidate: 60-300	Changes infrequently
Collections	revalidate: 300-3600	Rarely changes
Cart	no-store	User-specific, changes constantly
Customer	no-store	Private, per-session
Regions	revalidate: 3600	Almost never changes
Prices	revalidate: 60	May change with promotions

Server Actions

Server actions handle form submissions and mutations from server components:

// Fetch live docs for Next.js server actions
// with Medusa SDK mutation patterns
"use server"

Use Case	Action Pattern
Add to cart	Server action calling sdk.store.cart.addLineItem()
Update quantity	Server action with revalidatePath
Apply discount	Server action calling sdk.store.cart.update()
Customer login	Server action wrapping sdk.auth.login()

Use server actions for simple form mutations. Use API routes when external systems need to call your storefront.

Storefront Environment Variables

Variable	Purpose	Where Used
NEXT_PUBLIC_MEDUSA_BACKEND_URL	Medusa server URL	Client + Server
NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY	Store API key	Client + Server
REVALIDATE_WINDOW	Default ISR revalidation time	Server only

Best Practices

• Component boundaries — default to server components; add "use client" only for interactive elements; split pages into server (data) and client (interaction) sub-components
• SDK usage — initialize once in a shared module; use server-side calls in server components for SEO; use Tanstack Query in client components for reactivity and caching
• Caching discipline — cache product and collection data aggressively; never cache cart or customer data; use on-demand revalidation for admin-triggered updates; monitor cache hit rates
• Performance — use loading.tsx for streaming with Suspense boundaries; prefetch data for likely navigation targets; optimize images with next/image and Medusa media URLs

Fetch the Medusa Next.js storefront documentation and JS SDK reference for exact method signatures, query key conventions, and starter template patterns before implementing.