The complete guide
Shopify Hydrogen integration: the complete guide
Updated November 18, 2026 · Published by Danny Rathod, Founder, StackLift AI. Written with AI assistance; how we make content.
Short answer
Shopify Hydrogen is Shopify's React framework for building a custom, headless storefront. Your storefront reads products, carts, and customer data from Shopify's Storefront API, while Shopify keeps running checkout, orders, and the admin. You choose it when you need a front end that themes cannot deliver, and you accept more code to own.
What is Shopify Hydrogen?
Hydrogen is an open-source React framework made by Shopify for custom storefronts. Headless means the front end is separate from Shopify's theme system. Shopify still holds your catalog, carts, checkout, and orders.
Hydrogen has been built on the Remix and React Router lineage, and Shopify offers its own hosting for it, called Oxygen. Neither is required with the other. You can also build a headless storefront on a framework such as Next.js, using the same Storefront API.
When does a headless storefront make sense?
| Situation | Theme | Headless (Hydrogen or similar) |
|---|---|---|
| Standard store, standard layout | Good fit | More than you need |
| Heavily custom design and interactions | Hard to push further | Good fit |
| Content from several sources in one front end | Awkward | Good fit |
| Small team, limited engineering time | Good fit | Heavier to maintain |
| Many apps that inject storefront features | Works with the theme | Apps may need extra work |
If your goals fit a theme, use one. Headless is a trade of simplicity for control. See Shopify for the standard path.
How does a Hydrogen storefront work?
Your storefront runs server-side rendering on a JavaScript runtime and fetches data with GraphQL from the Storefront API. Access uses tokens created in Shopify's Headless sales channel. A private token stays on the server, and a public one may be used in the browser, within its scopes.
Customer accounts use Shopify's Customer Account API. Cart and checkout stay with Shopify, so the buyer is sent to its checkout to pay. That keeps payment handling in Shopify's hands.
You still use the Admin API and webhooks for back-office integrations, as on any Shopify build. Environment variables hold your tokens in each environment.
What data moves, and in which direction?
| Data | Direction | How often |
|---|---|---|
| Products, collections, and prices | Shopify to storefront | Per page, with caching |
| Cart lines and discounts | Storefront and Shopify | Per shopper action |
| Customer account details | Shopify to storefront | On login |
| Editorial content | CMS to storefront | Per page, with caching |
| Orders and inventory for other systems | Shopify to ERP, by webhook | Per event |
What drives the effort of a Hydrogen build?
The typical effort shown above covers a standard headless storefront. See ecommerce cost for ranges by project type.
- Design complexity, animations, and number of page types.
- Search, filters, and merchandising rules.
- Caching strategy for speed with fresh prices and stock.
- Content sources outside Shopify.
- Customer accounts, subscriptions, and loyalty features.
- Replacing features that theme apps used to supply.
- Hosting, previews, and release process.
What are the common Hydrogen pitfalls?
- Going headless when a theme would meet the goal.
- Losing features that apps added to themes, then rebuilding them by hand.
- Exposing a private token to the browser.
- Over-caching, so shoppers see old prices or stock.
- Weak SEO basics: metadata, structured data, redirects, and sitemaps.
- Underestimating ongoing maintenance as the framework evolves.
- No staging environment for design and content review.
Budget for ownership, not just the build. A headless storefront is code your team keeps running: dependency updates, framework changes, token rotation, and monitoring. Agree who does that work, and how often, before launch. Without a named owner, the storefront slowly falls behind, and the next upgrade becomes a large project instead of a routine one.
How do you test and launch a Hydrogen storefront?
- Build against a development store with realistic products.
- Test the full path: browse, search, cart, checkout handoff, and account.
- Check metadata, structured data, and redirects from old URLs.
- Test speed on real phones and slow connections.
- Check caching with a price and stock change.
- Launch behind a preview first, then cut over at a quiet time.
- Monitor errors and conversion paths, with rollback ready.
How does StackLift scope a Hydrogen build?
A senior architect reviews the scope before it becomes a commitment, including whether headless is the right call. The free estimate prices the work feature by feature. Agents work on feature branches and never touch production secrets, and CI/CD, observability, and rollback are part of the plan from sprint one. See also Shopify AI engineering.
Questions people ask
Is Hydrogen the same as headless Shopify?
Hydrogen is one way to build a headless Shopify storefront. You can also use the Storefront API from another framework.
Do I have to host Hydrogen on Oxygen?
No. Oxygen is Shopify's hosting option for Hydrogen, but the two are separate choices. Check Shopify's current documentation for hosting options.
Will my Shopify apps work with a headless store?
Back-office apps usually do. Apps that change the storefront through the theme may not, and you may need to rebuild that feature or use the app's API.
Is a headless store better for SEO?
Not automatically. It can be fast and flexible, but you must handle metadata, structured data, and redirects yourself.
Where does checkout happen on a headless store?
Shopify keeps checkout, so shoppers pay on Shopify's checkout. That keeps card handling with Shopify.
How much does a Hydrogen storefront cost?
It depends on design, page types, search, and integrations. See ecommerce cost for ranges by project type, or run the free estimate.