Headless with Hydrogen

Everything so far in this course assumes a Liquid theme rendering pages inside Shopify's own frontend system. A "headless" storefront takes the opposite approach: the frontend is a completely custom application, built with ordinary web frameworks, that fetches Shopify's data over an API instead of being rendered by Shopify itself. This lesson covers Shopify's own supported path for that: Hydrogen and Oxygen.

Why go headless at all

A theme covers the vast majority of stores well, so headless is a deliberate trade rather than a strict upgrade. It makes sense when a team needs frontend flexibility a theme's Liquid/section model can't easily provide — a highly custom, app-like shopping experience, tight integration with a non-Shopify content system, or a frontend engineering team that's already standardized on a particular JavaScript stack and wants to keep using it rather than learning Liquid.

What Hydrogen actually is

Hydrogen is a set of conventions and helper libraries built on top of React Router, a general-purpose React framework — not a Shopify-specific templating language like Liquid. A Hydrogen project is a React Router application from the ground up, pre-wired with routes for the pages a storefront typically needs (product, collection, cart, search, and so on) and a set of components tailored for rendering Shopify data:

app/
  routes/
    ($locale)._index.tsx
    ($locale).products.$handle.tsx
    ($locale).collections.$handle.tsx
    ($locale).cart.tsx

Each route defines a server-side data-loading function that runs before the page renders, fetching exactly what that page needs from Shopify's Storefront API — the same GraphQL API a theme's own JavaScript can call from the browser, but here it's the backbone the entire frontend is built on rather than an occasional supplement.

query ProductByHandle($handle: String!) {
  product(handle: $handle) {
    title
    priceRange { minVariantPrice { amount currencyCode } }
  }
}

Server rendering by default

Because each route's data loading runs on the server before the page is sent to the browser, a shopper's first view of a page arrives as fully-formed HTML rather than an empty shell waiting on client-side JavaScript to fetch data — generally better for both initial load speed and how easily search engines can read the page, at the cost of needing a server (or, here, an edge runtime) to actually run that loading logic on every request.

Oxygen: where a Hydrogen storefront actually runs

A React Router application needs somewhere to execute its server-side logic. Oxygen is Shopify's own hosting service purpose-built for this — a serverless runtime distributed across edge locations worldwide, so a request is handled from a server physically close to whoever made it. Deploying a Hydrogen project to Oxygen is a deliberate choice rather than the only option (a Hydrogen app can technically run on other hosting), but it's the path Shopify builds and documents first, and the one most projects use by default.

Headless still means real infrastructure

It's worth being honest about the trade-off: a theme comes with almost everything already built — cart behavior, checkout, account pages, SEO defaults. A headless storefront rebuilds the frontend side of all of that from scratch on top of an API, in exchange for full control over the experience. That's a meaningfully larger and more ongoing engineering commitment than customizing a theme, which is exactly why most stores stay theme-based and headless remains a choice for teams with a specific reason to need it.