Hydrogen

What changed in Hydrogen 2026-10?

Hydrogen used to be a framework. Storefronts were built on it from the start, first on Remix and later on React Router 7, and Hydrogen owned the server entry, the dev server and the build. If you wanted its cart or its analytics, your whole storefront had to be a Hydrogen app.

Version 2026-10, released as generally available on 14 October 2026, turns it into a library. Your framework keeps routing, data loading and rendering. Hydrogen supplies the Shopify-specific parts: the Storefront API client, the cart, variant selection, collection filtering, predictive search, Markets pricing, Shop Pay, customer accounts and first-party analytics with consent handling. It ships React and Vue bindings, and frameworks without a binding, such as Astro or SvelteKit, use the core directly.

Existing storefronts keep working. Shopify publishes a migration guide for stores on 2026-04 or earlier, and a store still on Remix moves to React Router 7 as part of that migration. The new version needs Node.js 22.12 or later.

How does a Hydrogen storefront work?

There are three layers. Your framework renders pages. Hydrogen runs request handlers around your router that answer the routes a Shopify storefront needs, like /api/cart, /checkout and cart permalinks, and checks the store's URL redirects before a visitor gets a 404. Shopify provides the Storefront API, the Customer Account API and checkout.

In the browser, Hydrogen keeps cart, product, collection and search state in small observable stores that your components read. Changes go back through native HTML forms, so a shopper can add to cart before JavaScript has loaded.

Hydrogen also implements Shopify's standard storefront events and actions, the same contract Liquid themes use. Compatible apps and AI shopping agents can read and update the cart on a Hydrogen storefront the same way they do on a theme.

What does Hydrogen leave to you?

The library is deliberately narrow. Your team still owns:

• The UI. Hydrogen ships no component library, so design, layout and styling are your code.
• Routes, loaders and the rendering strategy.
• Session storage for signed-in customers, and the account pages built from Customer Account API data.
• Images, through your framework's image component or srcset with Shopify CDN URLs.
• SEO: meta tags, Open Graph tags and structured data.

Checkout stays on Shopify, and Hydrogen has no Admin API client. Anything that writes to products, orders or inventory needs a separate backend integration.

Where can you host Hydrogen, and what does Oxygen cost?

Shopify offers two starters. The React Router 7 template deploys to Oxygen, Shopify's hosting. Vercel Shop, a Next.js 16 template maintained by Vercel, deploys to Vercel. Node, Cloudflare Workers and Deno also work if your framework already runs there.

Oxygen is included at no extra charge on paid plans: Starter, Basic, Grow, Advanced, Plus and Pause and build. It is not available on Agentic plans. Development stores and trial stores can deploy too, but they get no public environments, so every URL needs a store login. A live store gets one public environment on Starter, Basic, Grow and Advanced, and 25 on Shopify Plus.

Oxygen runs your code as a Web Worker on Cloudflare's workerd runtime, not as a Node server. Shopify's documentation lists limits such as 30 seconds of CPU time and 128 MB of memory per request. Node-only packages need replacing, and Shopify does not support putting a proxy in front of Oxygen, because it conflicts with bot protection and can cause SEO problems.

Should you use Hydrogen, a theme, or your own headless stack?

Start with the theme question. Shopify's own documentation says a headless storefront costs more to build and run than a theme, and that the merchant needs developers to maintain it after launch. If the goal is speed or a fresher design, a well-built Liquid theme is usually the cheaper answer. Our headless commerce entry covers that decision.

Once headless is settled, Hydrogen is no longer a choice of framework. Before 2026-10, the full toolkit came only with the Hydrogen framework, so a team on Next.js usually called the Storefront API directly and wrote its own cart, analytics and Markets logic. Synofit is an example of that route: a headless Shopify Plus store EVDEV built on Next.js, with the Storefront API, the Admin API and Contentful for content, for a Dutch health products brand whose range is stocked by more than 1,200 drugstores, health food shops and pharmacies. A stack like that can now add Hydrogen's primitives without changing framework.

Hydrogen is a poor fit when the frontend is not JavaScript, when you only need a buy button on an existing site (Storefront Web Components cover that), or when nobody will own the code after launch.

How do you set up a Hydrogen storefront?

1. Pick the starting point: run npx @shopify/hydrogen@latest setup inside an existing project, deploy the React Router template from the Shopify admin, or clone Vercel Shop for Next.js.
2. Install the sales channel that matches your hosting. The Hydrogen channel connects storefronts deployed to Oxygen. The Headless channel issues API credentials for storefronts hosted anywhere else, including Vercel.
3. On Oxygen, create the storefront in the admin. Shopify adds the environment variables your app needs; run npx shopify hydrogen link and npx shopify hydrogen env pull to use them locally.
4. Give every Storefront API query a cache strategy and pass the platform's cache and waitUntil function to the client.
5. Run Shopify's production checklist against a production build before launch.

What mistakes slow Hydrogen projects down?

No cache strategy. The client caches a query only when you give it one. Cache.long() keeps data for 1 hour and serves it stale for another 23 while it refreshes; Cache.short() uses 1 second and 9 seconds. Without strategies, every page view goes back to the Storefront API.

Exposing the private token. The private Storefront API token is a server secret. A NEXT_PUBLIC_ prefix in Next.js sends it to every browser.

Missing the buyer IP. Private Storefront API requests need the shopper's IP address. Each host sends it in a different header, such as oxygen-buyer-ip on Oxygen and x-forwarded-for on Vercel.

Request handlers wired only in development. Cart routes and redirects must run in the production server.

Assuming theme apps carry over. App blocks and script injections written for Liquid themes do not appear on a custom frontend. Check each app for a headless integration before launch.

Forgetting SEO. Shopify expects product URLs at /products/:handle. If you change that structure, add server-side redirects from the expected path, and write the meta tags and structured data yourself.

If you are weighing Hydrogen against a theme or an existing Next.js build, our Shopify development team can review the architecture before code is written.