Shopify Hydrogen, edge-rendered.
React storefronts on Shopify Hydrogen 2.0 and Oxygen. For brands on Plus who have outgrown the Liquid theme ceiling and need server-rendered speed with Shopify-native commerce underneath.
Five tiers. One request path.
Most Hydrogen pages sell "headless." This page sells the architecture. Below is the actual cross-section: CDN edge, Oxygen runtime, Hydrogen framework, Storefront API, Shopify core. A request starts at the top, travels down, and returns. Every ceiling a Liquid theme hits sits somewhere in this stack, and knowing which tier the ceiling sits in is how you decide whether Hydrogen is the right answer.
| Tier | Name | What it does |
|---|---|---|
| 01 | CDN Edge | Global points of presence in front of Oxygen. Static asset caching plus rendered HTML caching where subrequests allow. First byte to the browser. |
| 02 | Oxygen | Shopify's managed V8 edge runtime. Runs React Router loaders server-side, handles subrequest caching, bridges CDN and Storefront API. Free for Plus merchants. |
| 03 | Hydrogen | The React framework itself. Now aligned with React Router 7. Cart utilities, Storefront API client, SEO helpers, Analytics hooks. |
| 04 | Storefront API | Shopify's public GraphQL Storefront API. Products, collections, cart, checkout, customer, metaobjects. Versioned quarterly. |
| 05 | Shopify Core | The commerce engine: orders, payments, inventory, fraud, tax, shipping, checkout. Never bypassed. Your Hydrogen storefront sits in front of the same engine a Liquid theme would. |
The critical fact buried in the table: Shopify core is untouched. A Hydrogen build does not replace Shopify; it replaces the storefront layer (Liquid themes) while keeping orders, payments, and checkout on the same commerce engine your Liquid theme uses today. That is why Hydrogen is not the same kind of decision as migrating from Magento to Shopify, which replaces the whole engine underneath.
The four ceilings that trigger a Hydrogen build.
Hydrogen is not a universal upgrade. It is a specific answer to four specific ceilings that a Liquid theme eventually hits. If none of these apply to you, a well-built Online Store 2.0 theme on Dawn will ship faster, cost less, and hire fewer engineers. If two or more apply, Hydrogen starts paying for itself in the first year.
Performance
Liquid themes with heavy merchandising, third-party apps, and hero media often bottom out at 60-70 on mobile Lighthouse. Hydrogen with Oxygen routinely hits 90+ because HTML is rendered at the edge and non-commerce work moves to React Router loaders.
Merchandising
Section-and-block architecture is powerful but plateaus when you need dynamic bundles, personalized collections, per-customer catalog views, or AB tests that run on the server. Hydrogen lets you compose components freely and keep the logic typed.
Content
Metaobjects are great for small content models. Beyond that, editors need a real CMS. Sanity, Contentful, or Storyblok plug into Hydrogen cleanly; plugging a CMS into Liquid is a fight.
Multi-locale
Shopify Markets handles many cases. When you need per-locale content trees, per-market merchandising, or per-region pricing tied to non-Shopify data sources, Hydrogen with a structured CMS expresses the architecture cleanly.
If you are not sure which ceiling you are hitting, the Hydrogen Audit in § 09 produces a written decision memo. The memo says "Hydrogen" or "stay on Liquid"; we have delivered both outcomes.
Five layers. One request.
The animation below shows the stack separating and recomposing, with a single request path threading through all five tiers. The amber line is one page view traveling from a browser at the edge down to Shopify core and back.
Named tools. Named versions.
We ship Hydrogen 2.0 on React Router 7, Oxygen for deployment, a structured CMS where content demands exceed metaobjects, and a tightly scoped tool list that every engineer on the project can hold in their head. The stack below is the default; each choice is swappable during Phase 1.
Hydrogen 2.0
React Router 7, server-rendered by default, cart utilities, Storefront API client, Analytics hooks. Upgraded automatically when Shopify ships a new API version.
Oxygen
Shopify's V8 edge runtime. Free for Plus merchants. Preview deploys per PR, production deploys on merge to main.
Sanity or Contentful
Structured content where metaobjects stop being enough. Sanity for editors who want inline editing; Contentful for enterprise governance.
TypeScript + GraphQL Codegen
Generated types off Storefront API schema. Compile-time verification that queries match the current API version.
Tailwind v4 + Radix primitives
Utility-first with accessible unstyled primitives. Design tokens mapped to your brand system, not a Dawn offshoot.
Sentry + Shopify Web Pixels
Error tracking plus commerce event stream. First-party analytics via Shopify's Web Pixels Manager.
Vitals we refuse to ship without.
Hydrogen only pays back when it is measurably faster than the Liquid theme it replaces. Below are the web.dev Core Web Vitals thresholds we gate on before DNS flips. If any metric is red on the top five URLs, the cutover does not happen that week.
| Metric | Gate | How we get there |
|---|---|---|
| LCP | < 2.0s | Hero image preload, server-rendered HTML, image CDN at edge, critical CSS inlined. |
| INP | < 150ms | Code splitting per route, third-party script budget, React 19 transitions for cart interactions. |
| CLS | < 0.05 | Explicit image dimensions, font-display swap with preload, skeleton states on loader boundaries. |
| TTFB | < 300ms | Oxygen edge rendering, subrequest caching on Storefront API, HTTP cache headers from loaders. |
| Bundle | < 120KB gz | Tree-shaken imports, no heavy client libraries, icon set shipped as SVG sprite, tailwind JIT output. |
Thresholds are mobile p75 on PageSpeed Insights against CrUX field data where available, and Lighthouse synthetic otherwise. Before/after vitals are captured at kickoff and at launch, published in the handoff document.
Oxygen by default. Off-Oxygen when it pays.
Oxygen is free for Plus merchants and ships preview URLs per pull request, global edge CDN, and automatic environment management. For most brands it is the right default. We recommend off-Oxygen (Vercel, Cloudflare Workers, or self-hosted) only when the organisation has existing infrastructure contracts that make Oxygen redundant, or when a specific runtime feature is required that Oxygen does not yet support.
- Free for Plus merchants. No hosting bill.
- Preview URLs per PR automatically.
- 100+ global edge points of presence.
- Custom domains + SSL managed by Shopify.
- Integrated with Shopify auth for storefront access tokens.
- Zero ops for your team.
- Existing Vercel or AWS contract with team-wide seats.
- Need for non-V8 runtime (Node-only libraries, Python workers).
- Co-location with non-Shopify services that share a region.
- Specific edge feature (KV stores, Durable Objects) Oxygen does not offer.
- Compliance requirement for self-hosted or government-cloud deployment.
- Budget $50 to $500 per month added for hosting.
Who a Hydrogen build fits, and who it does not.
Hydrogen is the right answer for a specific shape of brand. If your shape does not match, a Liquid theme ships faster, costs less, and keeps your engineering team free for the work that actually moves revenue.
- Shopify Plus with $2M to $50M per year and a committed engineering team of six or more.
- Hitting two or more of the four ceilings in § 02 (performance, merchandising, content, multi-locale).
- Content-heavy storefront where editorial and commerce mix on the same pages.
- Brand with 12 to 24 month horizon for Hydrogen to pay back. Not a Q4 project.
- React-comfortable engineering team able to own the codebase after handoff.
- Under $1M per year. The engineering cost outruns the CWV payback. Ship on a well-built Liquid theme instead.
- Need to launch in under 12 weeks. Hydrogen builds do not compress below 10 weeks; tight deadlines belong on Liquid.
- Team cannot maintain React. We will not hand you a codebase your team cannot own.
- Theme polish is the actual problem. Hydrogen is a framework, not a better paint job. Liquid polishes fine.
- Under 1,000 orders per month. The throughput does not justify the additional surface area.
Liquid to Hydrogen. Before / after.
An Emani-archetype beauty brand on Shopify Plus came to us at 62 mobile Lighthouse with a Liquid theme that had grown 40+ apps over three years. The ask: hit 90+ mobile, cut time-to-interactive in half, rebuild the merchandising engine so the content team could stop waiting on developers.
What shipped: Hydrogen 2.0 on Oxygen, Sanity CMS for editorial, Shopify metaobjects for product metadata, Klaviyo and ReCharge preserved via API. 40+ apps audited, 18 kept, 22 replaced by native React components. SEO: 301 redirect map on 1,200 URLs, ranking parity restored within 21 days of DNS flip.
Four shapes. One of them fits.
Hydrogen Audit
CWV baseline, Storefront API gap analysis, deployment recommendation, go / no-go memo. Deliverable is yours either way.
Greenfield Build
Full Hydrogen storefront on Oxygen with CMS. Shopify commerce primitives preserved.
Liquid Migration
Replatform Liquid to Hydrogen. 301 map, SEO preservation, cutover rehearsal, soft launch.
Retainer
Ongoing engineering, API upgrades, CWV protection, PR review. Named engineer.
Six questions Plus teams ask.
When does Shopify Hydrogen beat a Liquid theme?
Hydrogen wins when your storefront is CWV-bound on mobile, when your merchandising needs outrun Online Store 2.0 sections, when you need a multi-locale multi-currency architecture that Markets cannot express cleanly, or when content editors need a CMS with deeper structure than metaobjects. Hydrogen loses when your team is under six engineers, your throughput is under 1,000 orders per month, or when your biggest problem is theme polish. A Liquid theme solves the theme-polish case faster, cheaper, and with less hiring pressure.
Do we have to give up Shopify apps when we go headless?
Partially. Any app that injects a Liquid snippet into the theme will not run on a Hydrogen storefront. Apps that expose an API or a webhook (Klaviyo, ReCharge, Gorgias, Judge.me) will still work, you just wire them into your React components rather than accept a snippet drop. App compatibility is audited in week one of any Hydrogen build, and the replacement path for each incompatible app is written into the decision memo before the build starts.
What is Oxygen and do we have to use it?
Oxygen is Shopify's managed V8 edge runtime for Hydrogen. It is free for Shopify Plus merchants and deploys to a global CDN automatically. You do not have to use it. Hydrogen can also deploy to Vercel, Netlify, Cloudflare Workers, or any Node host. Choosing off-Oxygen adds a hosting bill and removes the free built-in CDN, but gives you flexibility if your infrastructure sits elsewhere already.
How long does a Hydrogen migration from Liquid take?
A Liquid-to-Hydrogen migration runs 14 to 18 weeks for a mid-market catalog (500 to 5,000 SKUs, one to three locales). Greenfield Hydrogen builds run 10 to 14 weeks. Both numbers assume the product data lives in Shopify and does not need to be migrated from another platform. Add 4 to 8 weeks if you are also migrating from WooCommerce, Magento, or BigCommerce at the same time.
Does Hydrogen hurt SEO compared to Liquid?
A well-built Hydrogen storefront beats most Liquid themes on SEO. Server-rendered React means Googlebot gets fully rendered HTML on first request, and Oxygen ships that HTML from an edge location near the crawler. Hydrogen also gives you granular control over JSON-LD, canonical tags, hreflang, and sitemap generation. The risk is not the framework, it is the migration itself: without a careful 301 map and a staged cutover, a replatform can drop rankings. The audit and cutover rehearsal in our scope exist to manage that risk.
What does a Hydrogen build actually cost to run per month?
If you deploy on Oxygen (free for Shopify Plus), your headless runtime cost is zero. You still pay Shopify Plus, Storefront API is included, and your only marginal cost is the optional CMS (Sanity, Contentful) at $100 to $1,500 per month depending on seats and bandwidth. Off-Oxygen deployments add hosting: expect $50 to $500 per month on Vercel or Cloudflare for typical traffic. The math usually favours Oxygen unless you already pay for a team-wide Vercel or AWS contract.
A two-week audit. A go or no-go memo.
The fastest way to answer "should we go headless?" is to book the Hydrogen Audit. Two weeks, standalone scope, and a written memo that either greenlights a build or tells you to stay on Liquid. Either answer saves you a quarter of wasted engineering.
Book my 30-minute Hydrogen audit call