Yuvraj Raulji | Headless architecture
Once decoupling is decided, almost everything that follows is downstream of one question: what renders where, and when. Get that right and caching, preview, cost and the failure modes all fall into place. Get it wrong and no amount of front-end work recovers it, because you are fighting the shape of the system rather than its details.
Direct answer
The first decision is rendering: which pages are built at deploy time, which are cached at the edge and revalidated, and which genuinely need to render per request. Product and collection pages usually belong in the cached tier, cart and account per request. Everything else follows from that: cache invalidation has to be driven by commerce webhooks rather than by time, the API boundary should expose what the storefront needs rather than mirroring the platform schema, preview needs a path that does not bypass the cache design, and every third-party call needs a defined behaviour when it fails.
Best suited for
- A headless build about to start
- A storefront whose cache nobody can reason about
- Content preview that fights the rendering strategy
- Multi-channel storefronts sharing one commerce backend
What this page is not
This page assumes decoupling is already decided. If it is still an open question, the honest first step is testing whether it would pay at all, because most stores asking for headless want something cheaper.
The problem
The symptom as the person carrying it would describe it, and the part that shows up in the numbers rather than in the ticket queue.
Nobody can say what is cached and for how long
What it costs
Stale prices, stale stock, and a team afraid to change caching in case something breaks. Cache behaviour that cannot be reasoned about becomes cache behaviour nobody touches.
The storefront renders everything per request
What it costs
The decoupled front end is slower than the theme it replaced and costs more to run. This is the commonest way a headless build fails to deliver the thing it was sold on.
Preview and production disagree
What it costs
Editors cannot trust what they see, so content goes live to be checked. The workflow degrades into publishing as testing, which is exactly the thing decoupling was supposed to improve.
One slow third-party call takes down the page
What it costs
A reviews widget or a personalisation service has no timeout and no fallback, so the storefront inherits the availability of its least reliable dependency.
Approach
In this order, and the order is the opinion. Most of what goes wrong on this kind of engagement is a step taken before the one it depends on.
Decide rendering per template
Static, cached and revalidated, or per request, chosen for each template against how often the data changes and how much staleness costs. A single site-wide answer is how storefronts end up either stale or expensive.
Drive invalidation from commerce events
Webhooks on price, stock and publish, invalidating precisely what changed. Time-based revalidation is a guess, and it is either too slow for stock or too expensive for everything else.
Design the API boundary deliberately
Expose what the storefront needs rather than mirroring the platform schema. Over-fetching from GraphQL is the standard performance failure in these builds, and it is a boundary design problem rather than a query tuning one.
Give preview a real path
Editors need to see unpublished content without bypassing the rendering model in a way that hides cache bugs until launch. Preview designed late is preview that contradicts production.
Define every failure mode
Timeouts, fallbacks and degraded states for each third-party call, decided before launch. A storefront should lose a reviews widget rather than a page.
Scope
Rendering
Static and cached tiersIncremental revalidationPer-request boundariesEdge and CDN strategy
Data
Storefront API designGraphQL query shapeOver-fetch eliminationSearch and filtering
Platform
Next.jsShopify Storefront APIMagento GraphQL and PWA StudioHeadless CMS boundary
Operations
Cache invalidation from webhooksPreview and draft modeFailure modes and fallbacksDeployment and rollback
Proof
A headless storefront where rendering strategy carried the result, and a B2B platform built over an explicit API boundary.
Headless commerce · Fashion
Headless fashion storefront
High-performance headless commerce architecture for India’s fastest-growing men’s fashion brand.
HeadlessStorefront APIPerformance
Custom platform · B2B
Procurement and approvals platform
Scalable B2B procurement platform streamlining purchase requests and approvals.
B2B workflowsApprovalsIntegrations
Outcome
A cache anyone on the team can explain
The durable outcome of architecture work is not a diagram. It is that a new engineer can say what is cached, for how long, and what invalidates it, which is the property that lets the storefront keep changing safely.
Failure that degrades instead of stopping
Every third-party dependency has a timeout and a defined fallback, so the storefront survives its least reliable integration. That is a design decision, and it is only cheap before launch.
No Lighthouse score or response-time figure is quoted here. Headless performance is a property of the rendering and caching choices rather than of the approach, so a number from another build tells you about its architecture and nothing about yours.
Questions
- What rendering strategy should a headless storefront use?
- Per template rather than site wide. Product and collection pages usually belong in a cached tier that revalidates on commerce events, because their data changes on a known trigger. Cart, checkout and account render per request. Marketing pages are often fully static. A single strategy applied everywhere is either stale or expensive.
- How should cache invalidation work?
- Driven by webhooks from the commerce platform on price, stock and publish events, invalidating precisely the affected pages. Time-based revalidation is a guess about how often things change, and on a commerce catalogue it is wrong in both directions at once.
- Hydrogen or Next.js for a Shopify headless build?
- Hydrogen is closer to Shopify's own primitives and Oxygen hosting; Next.js is more general and easier to staff for, and it suits builds that also serve non-commerce content. The decision is usually about the team you will have in two years rather than about the framework's features today.
- Why is our GraphQL slow?
- Almost always over-fetching. Storefront queries that mirror the platform schema pull far more than the template renders, and the fix is designing the boundary around what the page needs rather than tuning the query afterwards. This is the single most common performance failure in headless commerce builds.
- How do editors preview content in a headless build?
- Through a draft mode that renders the same components against unpublished data, on a path that does not silently bypass the caching model. Preview designed after launch tends to hide cache behaviour that then surfaces in production.
Next step
Describe what is actually in front of you and we will work out whether this is the right piece of work before anyone scopes it. That conversation is usually shorter than people expect, and it occasionally ends with me saying you do not need the project.