Rendering strategy for a headless storefront

"Server or edge" is a question about where your code runs. The thing a buyer experiences is a question about how much work happens between their tap and the first byte, and there are four places that time goes: the network hop from the buyer to whatever answers, any hop from there to your data, the queries themselves, and the rendering. Edge execution shortens the first of those. It does not shorten the others, and in some layouts it lengthens them.

That matters because the pages people most want to speed up are the ones where the other three dominate. A cached product page never reaches your application at all, so where the application lives is irrelevant to it. A cart page has to query live data per buyer, so moving the renderer closer to the buyer moves it no closer to the data. The pages left over — uncacheable, but not because of anything personal — are the ones where running at the edge genuinely changes a number.

So the first task is not choosing a runtime. It is sorting every route into what can be built ahead of time, what can be cached and for how long, and what must be rendered fresh for one person. That sort is the rendering strategy. The runtime is an implementation detail of the third bucket.

Hydrogen makes the caching model explicit rather than incidental, and its defaults are worth knowing before you reason about anything else. Shopify documents CacheShort() as public, max-age=1, stale-while-revalidate=9, CacheLong() as public, max-age=3600, stale-while-revalidate=82800, and CacheNone() as no-store. The detail that catches teams out is the default: Shopify documents that a sub-request with no cache option specified is cached at public, max-age=1, stale-while-revalidate=86399. A query you never thought about is being served stale for up to a day.

There are two layers here and they fail differently. Sub-request caching stores the API response; full-page caching stores the rendered HTML. A route can have every query correctly marked CacheNone() and still leak, because the assembled page went into a shared cache. Shopify documents the fix directly: set Cache-Control on the response — no-store where nothing may be stored anywhere, private, max-age=<seconds> where the browser may keep a copy but shared caches may not.

Once that is in place, count the traffic. On a typical catalogue storefront the overwhelming majority of requests are for pages that are identical for everyone, and those are answered by a CDN regardless of where your renderer runs. The pages that reach the renderer are a fraction. Choosing a runtime is a decision about that fraction, and it should be sized accordingly rather than argued about for a month.

This is the one thing on this page worth checking in your own codebase today, because it is invisible until traffic arrives.

When a storefront renders on the server with a private access token, Shopify sees every buyer as one client — your server. Shopify's documentation is explicit about the consequence: without the Shopify-Storefront-Buyer-IP header on requests that result from buyer traffic, Shopify cannot differentiate requests from different buyers, which can result in throttled API requests, limited bot protection, and unauthenticated flows at checkout.

That last item is the expensive one. A buyer arriving at checkout without their session carried across is a lost order, and it will present as an intermittent, unreproducible complaint rather than an error in your logs. The header is one line. Add it, and confirm it survives whatever proxy or CDN sits in front of your application, because a stripped or rewritten client IP produces the same symptom.

The contrast with client-side access is instructive. Shopify documents that Storefront API public access capacity scales with the number of buyers, based on their IP address, and that buyer traffic is not subject to a fixed per-minute request limit. Rendering in the browser inherits that model for free. Rendering on the server means you have to reconstruct it deliberately — which is a genuine cost of server-rendering, and one that almost never appears on an architecture diagram.

Hydrogen fetches in loader functions, and the documented pattern is to defer non-critical data so the response can start before every query has finished. Used well this is the single largest time-to-first-byte win available on a server-rendered storefront. Used badly it produces a page that appears fast and is unusable for another second.

The test for whether something is critical is not how important it is commercially. It is whether the page is wrong without it. A product page is wrong without its title, its price and its main image — a visitor who sees a heading and an empty price box has been shown a broken page, and a crawler that renders before the fill-in has indexed one. A product page is not wrong without its review summary, its recommendation rail or its recently-viewed strip; those can arrive whenever they arrive.

The failure mode to watch is layout shift, because deferral trades server time for client instability. Anything deferred needs its space reserved in the initial HTML at the size it will occupy. If you cannot know that size, the thing you are deferring probably belongs below the fold, and if it is below the fold you could equally have fetched it in the browser and kept the page cacheable.

Work through that list honestly on a typical mid-market catalogue and a pattern emerges: nearly everything is cacheable, the uncacheable remainder is cart and account, and cart and account are slow because of query count and API latency rather than geography. Which means the rendering strategy that wins is the boring one — server-render, cache hard, keep personal data out of shared caches — and it is available on every host, including the plainest single-region one.

It is also, notably, what a Liquid theme on Shopify's own CDN was already doing. If the case for your headless build rested on rendering speed and the honest strategy turns out to be "cache the pages", that case has not survived contact with the routing table. There are good reasons to go headless — a front end shared with a native app, an interface a theme genuinely cannot express, content composed from several systems — and this post is not an argument against any of them. It is an argument against buying a rendering architecture to solve a caching problem.

Whatever you choose, choose it per route and keep it reversible. A storefront where one template renders differently from the rest is not an inconsistency to be tidied up; it is the shape of a system that has been measured.

• Headless Shopify development
• Storefront API caching: what can go stale and what cannot
• Headless for one template, theme for the rest