Shopify Hydrogen Explained: The Complete Guide to Headless Commerce in 2025

Hydrogen is a React app you have to babysit, not a theme you install

The first Hydrogen build I shipped taught me one thing fast: you're not customizing a storefront anymore, you're running a Remix application that happens to sell things. That distinction is the whole article. The moment a client signs off on Hydrogen, they've signed up to own routing, caching, SEO rendering, deploys, and a frontend team that can keep all of it alive. Most stores don't need that. A few absolutely do.

So before I talk about how to build one, I'll be blunt about when it's worth building at all.

What Hydrogen actually is

Hydrogen is Shopify's React framework for headless storefronts, built on Remix. You get components, hooks, and utilities wired up to the Storefront API, and you write your frontend in React instead of Liquid. The commerce backend (checkout, payments, inventory, orders) stays on Shopify. You're only replacing the storefront layer.

Worth knowing the history because it explains the API: Hydrogen v1 was its own thing. Shopify bought Remix and rebuilt Hydrogen on top of it (v2). That's why everything is loader functions, file-based routes, and Remix data conventions now. If you've written Remix, you already know 80% of Hydrogen. If you haven't, learn Remix first, then add the Shopify bits.

When it's worth it (and when it isn't)

I don't recommend Hydrogen by default. Online Store 2.0 with a good theme handles the vast majority of stores, including ones doing serious revenue. If a JSON template and some sections solve the problem, that's the answer, and it's cheaper to maintain.

I reach for Hydrogen when the storefront genuinely needs a React architecture a theme can't fake:

• A buyer experience that's basically an app (configurators, 3D viewers, heavy interactivity)
• A content model too complex for metaobjects-in-Liquid to handle cleanly
• Performance requirements where I need full control over what JS ships and how data is cached
• A team that already lives in React and will own this thing long-term

If none of those are true, you're taking on an application's worth of maintenance for a coat of paint. I've watched brands pick headless purely because it sounded modern, then drown in the upkeep. I dig into that tradeoff more in is headless commerce worth the hype — short version: the bill comes later, not at launch.

The parts you have to understand

Storefront API

Everything flows through the Storefront API, which is GraphQL. You ask for exactly the fields a page needs and nothing else. This isn't a nicety. Over-fetching is the most common reason a Hydrogen page feels slow, because you're paying for the bytes and the resolution time on every request. Tight queries are a performance feature, not just clean code.

Server-side rendering and streaming

Hydrogen renders on the server and streams. The page can start painting as soon as the first chunk of data resolves instead of blocking on the slowest query. Shopify's been moving the stack toward React Server Components to cut client JS, and that direction matters because the less JavaScript you hydrate, the faster the thing feels on a mid-range Android phone, which is what most of your customers are actually on.

Caching — this is where builds live or die

Hydrogen gives you cache control at the sub-request level, and using it well is the difference between a fast store and an expensive one. You set strategies per query:

export async function loader({context}: LoaderFunctionArgs) {
  const {product} = await context.storefront.query(PRODUCT_QUERY, {
    variables: {handle: 'aergo-table'},
    cache: context.storefront.CacheLong(), // descriptions, titles, images
  });

  return {product};
}

Product copy and images can sit in CacheLong. Inventory and price you keep fresh or skip the cache entirely. Get this wrong in one direction and you serve stale stock; wrong in the other and you hammer the Storefront API on every request and your TTFB tanks. Most of my caching effort on a Hydrogen build goes into deciding, query by query, how stale each piece of data is allowed to be.

Getting a project running

Scaffold it

npm create @shopify/hydrogen@latest

It'll ask you for a template. For learning, point it at Mock.shop so you're not blocked on store setup. For a real build, connect the actual store.

Connect the store

You need the Headless sales channel installed on the Shopify store. That gives you a Storefront API access token, which goes in your .env. No token, no data, so this is the first thing to get right.

Routes and loaders

File structure is your router, same as Remix. A product page lives at app/routes/products.$handle.tsx, and you fetch its data in a loader:

query ProductPage($handle: String!) {
  product(handle: $handle) {
    id
    title
    descriptionHtml
    variants(first: 50) {
      nodes { id title availableForSale }
    }
  }
}

That's the shape I want every product query to have — the exact fields the page renders, nothing speculative. If you find yourself pulling first: 250 of something the page never shows, that's the bug.

Oxygen is the easy part

Hosting used to be the headless headache. Shopify mostly solved it with Oxygen, their global hosting for Hydrogen, running on Cloudflare Workers. Deploys go out to the edge, so your storefront is served close to the customer and latency stays low. It's tied into the Shopify dashboard, preview URLs and all, and for most builds it's the path of least resistance. You can self-host Hydrogen elsewhere, but unless you have a specific reason, Oxygen is what I use.

Hydrogen vs. plain Next.js for Shopify

People ask me this constantly, so here's my honest read. You can absolutely build a Shopify storefront in plain Next.js hitting the Storefront API yourself, and I've done both. The difference is how much Shopify-shaped work is already done for you.

Hydrogen ships cart logic, the analytics events Shopify expects, SEO helpers, and Oxygen deployment as a package. In Next.js you wire all of that by hand — the cart state machine, the customer account flow, the analytics that make Shopify's reports work. None of it is hard, but it's real time, and it's time spent rebuilding things Hydrogen gives you free.

I pick Next.js when the store is one slice of a bigger app — a marketing site, a dashboard, a marketplace — where Shopify isn't the center of gravity. I pick Hydrogen when the storefront is the product and I want Shopify's batteries included. If you're already strong in Next.js and the App Router, the gap is smaller than the marketing suggests; a lot of what makes either one fast comes down to the same fundamentals I cover in Next.js 14 performance optimization.

A build that actually justified it

A furniture brand wanted a 3D room planner on product pages: drop a piece into a rendered room, rotate it, check it against a wall. In a Liquid theme that's a fight with script tags and a slow, janky result. In Hydrogen it's just React. We pulled product and variant data through GraphQL, rendered the model with Three.js inside a component, and ran add-to-cart through the Storefront API, all in one app with shared state. That's a case where headless earned its keep, because the experience genuinely couldn't exist cleanly on a theme. Most stores don't have that requirement. This one did.

Where Hydrogen builds go wrong

Going headless moves responsibility from theme customization to application ownership. Here's what actually bites teams, in roughly the order I see it:

• Headless for looks. Picking it because it sounds premium, with no requirement a theme couldn't meet.
• SEO as an afterthought. No plan for meta tags, canonical URLs, or structured data, so rankings slide post-launch. On a theme you got a lot of this for free; now you own it.
• No cache strategy. Storefront queries with default or no caching, then surprise at the latency and API usage.
• App gaps. A theme-dependent app (reviews, upsells, whatever) that has no headless path and quietly stops working.
• No one to maintain it. The build ships, the agency rolls off, and there's no internal React owner. Now it's abandonware that takes payments.

If speed is the goal and a theme is technically on the table, fix the theme first. A lot of "we need headless for performance" turns out to be solvable on Liquid — I walk through that in store speed optimization and conversions.

How I'd scope a Hydrogen project

I don't write a line of Hydrogen until there's a short memo proving a theme can't do the job. It protects the client from owning a custom app they didn't need. The questions I work through:

• Can Online Store 2.0 solve this with less maintenance?
• Who owns React, routing, caching, SEO, and deploys after launch?
• Does the team actually need Storefront API control, or does it just sound nice?
• Are the app and checkout constraints understood up front?
• Is there a real content and analytics plan, not a hope?

If the answers hold up, I prototype one product route and one collection route, confirm SEO renders correctly, test the checkout handoff, and document deployment and rollback — before building the rest. If the prototype's already fighting me, that's cheap information.

FAQ

Is Hydrogen free? The framework is open source. Oxygen hosting is included with Shopify plans, but you're paying for the build and ongoing maintenance, which is the real cost of going headless.

Do my Shopify apps still work? Theme-based apps (anything that injects into Liquid) generally don't carry over. Apps with a proper API or app-block path can be integrated manually. Audit every app you depend on before committing, because this is where projects stall.

Do I have to use Oxygen? No. Hydrogen runs on other platforms, but Oxygen is the smoothest path and what I default to unless there's a reason not to.

Hydrogen or Next.js? Hydrogen if the storefront is the whole product and you want Shopify's commerce logic built in. Next.js if commerce is one piece of a larger app you're already running.

Docs I keep open

• Hydrogen React: https://shopify.dev/docs/api/hydrogen-react/latest
• Hydrogen updates: https://hydrogen.shopify.dev/updates