Medusa Storefront Performance: Where the Milliseconds Actually Go

Headless storefronts are supposed to be fast. Plenty are not, and the reasons are boringly consistent: they fetch too much, they fetch sequentially, they render dynamically when they could render statically, and they ship enormous images.

In rough order of impact, here is where the time goes.

1. Over-fetching

A default product list returns far more than a grid renders:

// ~180KB for 24 products
const { products } = await sdk.store.product.list({ limit: 24 })

// ~35KB, renders identically
const { products } = await sdk.store.product.list({
  limit: 24,
  region_id: region.id,
  fields: "id,title,handle,thumbnail,*variants.calculated_price",
})

Five times less data over the wire and through JSON parsing. Audit every list call before launch — see the SDK guide for the fields syntax.

The same applies to what crosses the server-client boundary. Passing a full product object into a client component serialises all of it into the HTML payload. Pass the four fields the component uses.

2. Dynamic rendering that should be static

// ✗ Dynamic on every request: an API round trip before the first byte
export default async function CategoryPage({ params }) { … }

// ✓ Static HTML, refreshed hourly
export const revalidate = 3600
export async function generateStaticParams() { … }

Anything identical for every visitor should be static: home, categories, products, content pages. Only cart, checkout and account need to be dynamic.

The usual accidental cause is calling cookies() or headers() in a layout, which opts the entire subtree into dynamic rendering. If your product pages went dynamic without you asking, look for a cookies() call in a shared layout.

3. Request waterfalls

// ✗ ~600ms — three sequential round trips
const region = await getRegion(countryCode)
const product = await getProduct(handle)
const related = await getRelated(product.collection_id)

// ✓ ~250ms — the independent pair runs in parallel
const [region, product] = await Promise.all([
  getRegion(countryCode),
  getProduct(handle),
])
const related = await getRelated(product.collection_id)

Only the genuinely dependent call stays sequential. On a page with four or five fetches this is routinely a 300–500ms saving, and it is free.

4. Images

Nearly always the LCP element on a product page.

<Image
  src={product.thumbnail!}
  alt={product.title}
  width={800}
  height={800}
  priority                                    // hero only
  sizes="(max-width: 768px) 100vw, 50vw"
  quality={80}
/>

• +priority on the hero and the first row of a grid. Nothing else — marking everything priority is the same as marking nothing.
• +Accurate sizes, or the browser downloads a desktop-sized image for a phone.
• +quality={80}. The visual difference from 100 is invisible; the size difference is not.
• +Serve from a CDN with a long cache lifetime.

5. Caching with precision

export const getProduct = (handle: string) =>
  unstable_cache(
    async () => { /* … */ },
    ["product", handle],
    { tags: [`product-${handle}`, "products"], revalidate: 3600 },
  )()

Tags let a webhook invalidate exactly what changed rather than dropping the whole cache. Wire it to a subscriber on product.updated. Patterns in the storefront guide.

Backend-side, a Redis cache module helps repeated price and region computation. Caching strategy.

6. JavaScript

Headless storefronts accumulate client components. Two habits keep it in check:

Default to server components. Add "use client" only where there is interactivity, and push it to the leaves — a client-side quantity stepper does not require a client-side product page.

Watch what you import into client components. A date library imported for one format call ships 70KB to every visitor.

Targets and measurement

Measure with field data, not lab data. Lighthouse on a developer laptop over office wifi is a fiction; Search Console's Core Web Vitals report is what Google actually uses.

A diagnostic order

When a page is slow, check in this order:

1. Is it static or dynamic? Static rendering removes the question.
2. What does the API response weigh? Fix fields.
3. Are fetches parallel? Look for sequential awaits.
4. What is the LCP element? Usually an image.
5. How much JavaScript ships? Find the accidental client component.

Four out of five slow storefronts are fixed by the first three.

Fonts

Usually the second-largest LCP contributor after images, and entirely avoidable.

import { Inter } from "next/font/google"

const inter = Inter({
  subsets: ["latin"],
  display: "swap",
  variable: "--font-sans",
  // Only the weights you actually use.
  weight: ["400", "500", "700"],
})

next/font self-hosts the files at build time, which removes a DNS lookup and a connection to a third-party host from the critical path. display: "swap" means text renders immediately in a fallback rather than staying invisible.

Two more: subset to the character sets you need, and ship no more than three weights. Every additional weight is another file on the critical path for a difference most visitors cannot see.

Third-party scripts

The other place performance quietly goes. Analytics, chat widgets, review platforms and pixels each add JavaScript that runs before your page becomes interactive.

import Script from "next/script"

<Script src="https://widget.example.com/chat.js" strategy="lazyOnload" />

Audit them quarterly. Every store accumulates scripts nobody remembers adding, and a chat widget loading on the checkout page is both a performance and a conversion problem.

A performance budget

Numbers in a CI check beat good intentions, because performance regresses one small addition at a time:

Enforce it with Lighthouse CI or a bundle-size check on every pull request, failing the build when a budget is exceeded. That converts "we should keep an eye on performance" into a conversation at the moment someone adds the dependency, which is the only time it is cheap to reconsider.

Review the budgets quarterly. They should get tighter as you remove things, not looser as you add them.

We do performance audits that end with a diff, not a slide deck. Ask.