Headless builds
Headless commerce, including the answer that you do not need it yet
We build Hydrogen storefronts on Oxygen and custom stacks against the Storefront API, for the cases where a theme genuinely cannot express what the store has to do.
And we test the case before building it. Most stores asking for headless want speed, or a design their current theme cannot manage, and both of those have cheaper answers that keep the theme editor and the app ecosystem.
- The cheaper alternative costed first
- Cutover mapped URL by URL
The problem
Why headless projects disappoint
Headless builds rarely fail technically. They deliver, and then the organisation discovers what it actually bought. Four disappointments account for most of it, and all four are foreseeable.
The merchandisers lost their controls
Everything that was a theme setting is now a deploy. The team who used to change a homepage before lunch now files a ticket, and velocity quietly halves.
The app ecosystem stopped applying
Storefront apps that installed themselves into a theme have nothing to install into. Each one becomes a build, and the ones that cannot be rebuilt become a loss.
Speed that did not survive the feature list
The build launches fast, then absorbs the same analytics, chat, review and consent scripts as before. The architecture was never what made it slow.
A storefront that now needs a team
A theme can go a year untouched. A custom application has dependencies, runtimes and security updates, and somebody has to own that permanently.
We treat headless as a trade rather than an upgrade. The build is worth doing when the thing you gain is something a theme genuinely cannot give you, and we would rather establish that before the rebuild than after it.
What headless actually means on Shopify
Headless means the storefront stops being a Shopify theme and becomes your own application, talking to Shopify over an API. Checkout, orders, inventory, payments and the admin all stay where they are. What you take ownership of is everything a customer sees before checkout, which is both the appeal and the entire cost.
The supported route is Hydrogen, Shopify’s own stack, which is built on React Router. That is worth stating precisely, because Hydrogen was built on Remix for years and a great deal of otherwise current writing still says so. Deployment is to Oxygen, Shopify’s edge hosting for Hydrogen, a worker-based JavaScript runtime based on Cloudflare’s workerd. Data comes from the Storefront API, with the Customer Account API behind anything logged in.
You are not obliged to use any of it. A headless storefront can be any framework on any host, reading the same APIs. The trade is support and integration against freedom: Hydrogen on Oxygen gives you a path Shopify maintains and documents, while a bespoke stack gives you complete control and a permanent obligation to maintain the parts Shopify would otherwise have maintained for you.
When headless is genuinely the right answer
There are real cases, and they share a shape: the storefront has a requirement that is structural rather than cosmetic, and a theme cannot express it at any budget.
- One front end serving several backends, where commerce is part of a larger product rather than the whole site
- A content or configuration experience genuinely beyond a theme: a configurator, a quoting flow, deep account functionality
- An existing application that has to absorb commerce rather than sit next to it, so a customer never crosses a boundary
- Several storefronts sharing one codebase across markets, where per-market themes have become the maintenance problem
- A front-end team you already have and already pay, who will own this permanently
That last one is not a nice-to-have and is the one most often waved through. Headless converts a storefront from something an agency can hand over into a piece of software with a maintenance obligation. If there is no team, in-house or retained, whose job this is next year, the project has a defect in it that no amount of build quality will fix.
When it is the wrong answer, which is more often
Most stores asking about headless want one of three things, and in each case there is a cheaper route that gets it without the trade.
| What you actually want | Is headless the answer? | What we would do instead |
|---|---|---|
| A faster store | Usually not | Performance work on the theme. Third-party scripts, not architecture, are almost always the cause |
| A design the theme cannot do | Rarely | A custom theme. Online Store 2.0 sections and blocks are far more capable than their reputation |
| To feel modern | No | Nothing. This is the reason that produces the abandoned rebuilds |
| A configurator or account experience a theme cannot express | Often yes | Headless, or a hybrid where only that route is custom |
The first row is the important one, because speed is the reason headless is sold most and the reason it delivers least. A headless storefront launches fast and then absorbs the same analytics, chat, review and consent tags the theme had, at which point it performs about the same. If the honest goal is Core Web Vitals, performance engineering on your existing store costs a fraction of a rebuild and addresses what is actually slow. We will say so rather than sell the bigger project.
The second row deserves the same honesty. A great deal of what merchants believe a theme cannot do is a description of the theme they bought rather than of the platform. A custom Shopify build reaches further than most people expect, and it keeps the theme editor, the app ecosystem and the ability to hand the store back to its owners.
What we build
What we build headless
Hydrogen and Oxygen
- Hydrogen storefronts on React Router, deployed to Oxygen, which is the route Shopify maintains and documents
- Storefront API and Customer Account API integration, including everything behind a login
- Rendering strategy chosen per route rather than per project, because a collection page and an account page have nothing in common
Custom stacks
- Next.js and other frameworks where an existing application has to absorb commerce rather than sit beside it
- Multi-storefront architectures where several markets share one codebase
- Honest ownership boundaries: what Shopify maintains, what we maintain, and what becomes yours permanently
Giving merchandising back
- Content and layout control rebuilt deliberately, so changing a homepage does not become a deploy
- Metaobjects and structured content modelled so your team edits meaning rather than markup
- Preview and rollback workflows your non-engineers can actually operate
Hybrid builds
- One custom route against the Storefront API with the rest of the store left as a theme
- A shared cart across the seam, so a customer never knows where one ends
- Reversible by design, which a full rebuild is not
What you give up, stated plainly
These are not risks to be mitigated. They are consequences of the architecture, and a proposal that does not name them is not a proposal you can evaluate.
- The theme editor. Merchandising moves from a settings panel into your codebase unless you deliberately rebuild that control, which is real work with no visible output
- The storefront app ecosystem. Apps that install into a theme have nothing to install into; each becomes an integration, and some have no headless path at all
- Preview and rollback as your team knows them. Both exist, and both become engineering workflows rather than admin buttons
- A permanently low floor of maintenance. Frameworks, runtimes and dependencies need updating whether or not you are changing anything
- The ability to hand the store to a small agency later. Your next supplier now needs front-end engineers, which narrows the field and raises the price
The merchandising point is the one that causes the most regret, and it is worth designing for explicitly rather than discovering. A team that could change a homepage before lunch will not accept filing a ticket for it, and if nothing replaces that control they will route around the system, usually by adding a tool that reintroduces exactly the weight the rebuild was meant to remove.
The middle option nobody offers
Headless is usually presented as a whole-store decision, and it rarely has to be. If the requirement is one route that a theme genuinely cannot express, that route can be the custom application while everything else stays a theme.
A configurator, a quoting flow or a deep account area runs as its own application against the Storefront API, and the collection pages, product pages, content and merchandising stay exactly where your team can already reach them. The cart is shared, so a customer never notices the seam. You take on the maintenance obligation for one route rather than for the entire storefront.
It is not the more impressive answer, which is most of why it goes unrecommended. It is very often the correct one, and it has the useful property of being reversible: a route can be folded back into the theme later, whereas a full rebuild cannot be undone without another full rebuild.
How it runs
How the decision and the build run
The first step can end the project, and sometimes should. That is what it is for.
- 1
The case, tested
What you want that a theme cannot give you, written down and challenged. If a custom theme or performance work would deliver it, we say so, and that is the end of the engagement rather than the start of a bigger one.
- The requirement stated structurally, not aesthetically
- Cheaper alternatives costed honestly
- Ownership after launch established before the build
- 2
Architecture and boundaries
What is custom and what stays theme, which APIs are involved, where merchandising control lives, and what your team will and will not be able to change without us.
- Hybrid considered before whole-store
- Merchandising control designed, not deferred
- Integrations mapped, including the ones with no headless path
- 3
Build
Routes built with rendering chosen per route, content modelled so it is editable, and performance treated as a budget agreed up front rather than a result discovered at the end.
- Rendering strategy per route
- Performance budget agreed before building
- Content editable by non-engineers
- 4
Cutover and handover
Redirects mapped one to one, launched in a quiet window, and handed over with the maintenance obligation written down. Whoever owns it next should learn what they own from a document rather than from an incident.
- Every URL mapped before cutover
- Deployed outside peak trading
- Maintenance obligations documented in full
Where this sits
This page exists to make the decision properly, and the decision is genuinely no more often than yes.
If the answer turns out to be a custom theme, that is Shopify development, the parent of this page. If the real goal was speed, it is performance engineering. If you are on WordPress and asking the same question, WooCommerce has its own version of it. And whichever architecture you land on, a rebuild is the point at which measuring the change stops being optional, because a replatform that moves revenue and cannot say why is a very expensive mystery.
The answers to your questions.
Not reliably, and this is the most oversold claim in the category. A headless storefront launches fast, then absorbs the same analytics, chat, review and consent scripts the theme carried, at which point it performs roughly the same. Third-party scripts, image weight and render-blocking resources are what make most stores slow, and none of that is architectural. If Core Web Vitals are the actual goal, performance work on your existing theme costs a fraction of a rebuild and addresses the real cause.
Hydrogen is Shopify’s own headless stack, built on React Router, and Oxygen is its edge hosting, a worker-based JavaScript runtime based on Cloudflare’s workerd. You are not obliged to use either: a headless storefront can be any framework on any host, reading the same Storefront API. The trade is support against freedom. Hydrogen on Oxygen gives you a path Shopify maintains and documents; a bespoke stack gives you total control and a permanent obligation to maintain what Shopify would otherwise have maintained for you.
The theme editor, so merchandising becomes a deploy unless that control is deliberately rebuilt. The storefront app ecosystem, since apps that install into a theme have nothing to install into and each becomes an integration. Preview and rollback as admin buttons rather than engineering workflows. And a permanently higher maintenance floor, because frameworks and dependencies need updating whether or not you are changing anything. The merchandising loss causes the most regret, because a team that could change a homepage before lunch will not accept filing a ticket for it.
Yes, and it is frequently the right answer. If one route genuinely needs what a theme cannot express, a configurator, a quoting flow, a deep account area, that route runs as its own application against the Storefront API while collections, product pages and content stay a theme your team can still edit. The cart is shared, so customers never see the seam. You take on the maintenance obligation for one route instead of the whole storefront, and it is reversible in a way a full rebuild is not.
You need somebody whose job it is, in-house or retained, and this is the question most often waved through. Headless converts a storefront from something an agency hands over into software with a permanent maintenance obligation: dependency updates, runtime upgrades and security patches arrive whether or not you are shipping features. If there is nobody who owns that next year, the project has a defect no amount of build quality will fix, and we would rather establish that before the rebuild than after it.
Checkout stays Shopify, along with orders, payments, inventory and the admin, so the parts under the most compliance pressure are unchanged. SEO is a genuine risk, but of execution rather than architecture: a headless storefront can render server-side and be indexed perfectly well, and the damage comes from cutovers that lose URL structures, metadata or internal linking. Every URL gets mapped one to one before launch, for the same reason it does on any replatform.
Been told you need to go headless?
Tell us what you want that your theme will not do, and who would own the storefront a year from now. We will tell you honestly whether this is the project you need.
Test the case with us ↗