What is Hydrogen?

How It Works

Hydrogen 2 (released late 2023) is a complete rewrite of the original Hydrogen 1 framework. Where Hydrogen 1 was a custom React Server Components implementation, Hydrogen 2 is built directly on Remix — Shopify's acquisition. This means every Hydrogen app follows Remix's routing conventions (file-based routes under app/routes/), loader/action functions for server-side data fetching and mutations, and the defer() pattern for streaming non-critical data after the initial HTML paint. Shopify adds its own layer on top: the @shopify/hydrogen package exports Storefront API utilities, React components, and hooks.

Data fetching in Hydrogen is done through the storefront object available in route loaders via the AppLoadContext. You write GraphQL queries (with optional #graphql tag for codegen) and Hydrogen handles the Storefront API authentication, response caching, and TypeScript type generation. The storefront.query() call also accepts a cache strategy parameter — CacheShort(), CacheLong(), CacheNone() — that controls how Oxygen's edge cache handles the response.

Hydrogen ships several purpose-built React components that encode Shopify best practices: <Money> renders localized prices using the cart's currencyCode and Intl.NumberFormat; <Image> wraps Shopify's CDN image transformation API with responsive srcset generation; <CartForm> is a Remix <Form> wrapper that submits cart mutations (add lines, update quantities, apply discount codes) to the appropriate action route. These components eliminate a significant amount of boilerplate and make the correct implementation the path of least resistance.

Why It Matters

Before Hydrogen, building a headless Shopify storefront required assembling a custom stack: a React (or Next.js) frontend, manual Storefront API integration, custom cart state management, and a separate hosting platform. Each team made different decisions and accumulated different tech debt. Hydrogen provides a blessed architecture — one that Shopify officially supports, documents, and maintains. The opinionated structure means new team members onboarding to a Hydrogen project have a known starting point.

The Oxygen hosting integration is the other major motivator. Oxygen is a V8 isolate-based hosting runtime (similar to Cloudflare Workers) deployed globally at Shopify's edge. When you push a Hydrogen app to Oxygen (via shopify hydrogen deploy), it runs in the same network as Shopify's Storefront API. Cache hit rates are higher, API latency is lower, and you get sub-100ms TTFB for most page loads globally. Oxygen is included in Shopify Plus subscriptions, making it effectively free for enterprise merchants.

The deferred loading pattern deserves special attention. Hydrogen's product page template wraps non-critical data (reviews, related products, recommendations) in Remix's defer() and uses <Suspense> boundaries on the client. The server starts streaming HTML immediately with the above-the-fold content; deferred promises resolve and stream in as their data arrives. This means a product page's critical content (title, price, add-to-cart button) renders before the Storefront API returns the recommendations response — real-world Lighthouse scores for Hydrogen stores routinely exceed 90 on mobile.

Alternatives and Related Concepts

The main alternative to Hydrogen is building a headless store with Next.js and the Storefront API directly. Next.js has a larger ecosystem, a broader talent pool, and App Router's React Server Components model can achieve similar streaming patterns. The tradeoff is that you lose the out-of-the-box cache strategies, the Oxygen integration, and the Shopify-specific primitives like <Money> and <CartForm>. For most Shopify-centric headless projects, Hydrogen is the faster path to production. For projects that require Next.js-specific features (e.g., Next.js Image optimization on a custom CDN, App Router parallel routes), Next.js + Storefront API is a valid choice.

Hydrogen is also distinct from Online Store 2.0 themes (Liquid-based storefronts hosted on Shopify's CDN). OS2.0 is simpler to deploy and doesn't require a separate hosting runtime, but Liquid templates cannot deliver the interactivity of a React SPA. Hydrogen is the right choice when you need client-side routing, complex cart interactions, or third-party integrations that require JavaScript.

To get hands-on with Hydrogen, run npm create @shopify/hydrogen@latest to scaffold a new project from the Shopify Demo Store template. See the Hydrogen documentation for the full API reference, including the cart tutorial that covers cartCreate and the useOptimisticCart hook.