Shopify Hydrogen is Shopify's toolkit for building headless storefronts: custom frontends that run on your own code while Shopify handles products, the cart, checkout and orders. Since Hydrogen 2026-10, released on October 14, 2026, it is a JavaScript library that you add to a framework such as React Router 7 or Next.js, not a framework of its own.
That is a big change from the Hydrogen that most articles still describe. This guide covers what Hydrogen is in 2026, what it runs on, how hosting and the APIs work, what has changed since 2024, and when a headless build is worth it compared with a Shopify theme. We build headless storefronts for clients, so the last part comes from real projects, not only from the docs.
What is Shopify Hydrogen?
Hydrogen is Shopify's official package for headless commerce. It is published on npm as @shopify/hydrogen under the MIT license. Shopify's docs call it "Shopify's headless toolkit" and "one way to build a headless storefront on Shopify."
In a headless setup, the storefront your customers see is a separate web app. It reads data from Shopify through APIs and sends shoppers to Shopify checkout to pay. Hydrogen gives that app the commerce parts it needs:
- A typed Storefront API client with caching.
- Request handlers for the routes Shopify owns, such as checkout, cart permalinks, URL redirects and the cart API.
- A cart that works before JavaScript loads and shows changes before the server replies.
- Variant selection, collection filters, sorting, pagination and predictive search.
- Money formatting, Shopify Markets context, Shop Pay buttons and Shopify analytics that respect consent.
- A Customer Account API client with login, logout and sessions.
Hydrogen no longer ships a component library. You build the pages with your own components and design system. Checkout stays on Shopify, and Hydrogen covers only the Storefront API and the Customer Account API, not the Admin API.
What is Hydrogen built on in 2026?
The short answer: on the framework you choose. The longer answer has three stages.
- Until May 2025: Remix. Hydrogen was a full-stack framework built on Remix, with its own CLI, components and project structure.
- May 2025 to October 2026: React Router 7. In May 2024 the Remix team announced that the planned Remix v3 would ship as React Router v7. React Router v7 became stable on November 22, 2024. Hydrogen 2025.5.0, released on May 21, 2025, moved from Remix 2 to React Router 7.
- From October 2026: any framework. On June 17, 2026, Shopify released a developer preview that "moves the commerce logic out of React Router into a framework-agnostic core." Hydrogen 2026-10 made it generally available on October 14, 2026.
Hydrogen 2026-10 has a core that does not depend on any framework, plus bindings for React and Vue:
@shopify/hydrogen: the core, with the Storefront API client, request handlers, cart, product form, collections, predictive search, money formatting, analytics and Shop Pay.@shopify/hydrogen/react: React components and hooks built on the core. The separate@shopify/hydrogen-reactpackage stays on the 2026-04 line.@shopify/hydrogen/vue: the same components for Vue, with composables instead of hooks.@shopify/hydrogen/customer-account: the Customer Account API client and customer session helpers.
Shopify maintains a React Router 7 starter that deploys to Oxygen. Vercel maintains Vercel Shop, a Next.js 16 starter built on Hydrogen. The Hydrogen repository also has examples for Nuxt, Astro, SvelteKit and SolidStart, but Shopify notes that these are test projects, not starters.
The core uses web platform APIs such as fetch, Request, Response and Web Crypto. That is why it runs on Oxygen, Node.js, Cloudflare Workers, Deno and Vercel. Shopify tests Hydrogen 2026-10 with React 19, Vite 8 and Node.js 22.12 or 24.
What is Oxygen, and where else can you host Hydrogen?
Oxygen is Shopify's hosting platform for Hydrogen storefronts. It runs your storefront as a Web Worker, not as a Node server, on a runtime based on Cloudflare's open-source workerd. You manage it from the Hydrogen sales channel in the Shopify admin, which holds each storefront's environments, environment variables and deployments.
What to know about Oxygen in 2026:
- Cost. Oxygen is included at no extra charge on paid Shopify plans from Starter to Plus. Shopify's October 2026 announcement says Oxygen "is still free."
- Testing. Since August 2026, development stores and trial plan stores can deploy to Oxygen as well. Their deployment URLs always require a store login, because they have no public environments.
- Deploys. You can deploy on every push from GitHub, from your own CI/CD, or from the terminal with
npx shopify hydrogen deploy. When you create a storefront, Shopify adds the Storefront API and Customer Account API variables for you. - Limits. A worker must be 10 MB or smaller and can use up to 128 MB of memory. Some Node.js APIs are not available, so check Shopify's Oxygen runtime docs before you add Node-only libraries.
You do not have to use Oxygen. Shopify's deployment docs describe three paths:
| Host | When it fits | Where the store connection comes from |
|---|---|---|
| Oxygen | You use the React Router starter and want Shopify to host it | Hydrogen channel |
| Vercel | You build on Next.js, for example with Vercel Shop | Headless channel |
| Node.js, Cloudflare Workers, Deno or another runtime | Your framework already deploys there | Headless channel |
Outside Oxygen, you create your Storefront API tokens in the Headless channel and pay your host separately.
Which Shopify APIs does Hydrogen use?
Two: the Storefront API for the shop and the Customer Account API for logged-in customers.
Storefront API
The Storefront API is a GraphQL API for products, collections, search, the cart and international pricing. When the shopper is ready to pay, it hands them off to Shopify checkout. It supports three kinds of access:
- Tokenless access for the basics, such as products, collections, search and the cart.
- A public token for requests from a browser or mobile app, where buyers can see the token.
- A private token for server requests, such as a Hydrogen backend, where the token stays secret.
Requests from real buyers have no fixed requests-per-minute limit. Automated traffic is limited.
Customer Account API
The Customer Account API powers logged-in pages: order history, profile and addresses. It authenticates buyers, not apps, and follows OAuth 2.0, with PKCE for public clients such as web and mobile apps. Hydrogen 2026-10 includes the client, login and logout handlers and customer sessions in @shopify/hydrogen/customer-account. It also adds a local HTTPS helper, because Customer Account API login does not work on plain localhost.
Hydrogen follows Shopify's quarterly API versions. Hydrogen 2026.10.x uses version 2026-10 of both APIs. Each stable API version is supported for at least 12 months.
What does the Hydrogen CLI look like now?
It is smaller than before. In Hydrogen 2026-10, your framework runs the dev server and the build. Shopify CLI commands such as shopify hydrogen dev, build, preview, codegen and upgrade work only with Hydrogen 2026-04 and earlier, and shopify hydrogen init still creates a 2026-04 project. These are the commands you use now:
| Command | What it does |
|---|---|
npx @shopify/hydrogen@latest setup | Installs Hydrogen and copies its agent skills into .claude/skills and .agents/skills. In an empty folder, it offers the React Router template. |
npx @shopify/hydrogen skills sync | Updates the agent skills to match the installed Hydrogen version. Run it after each upgrade. |
npx @shopify/hydrogen skills check | Fails when the skills are out of date, so you can run it in CI. |
npx @shopify/hydrogen gql check | Checks your GraphQL queries against the Storefront API schema. |
npx @shopify/hydrogen certs install | Sets up trusted local HTTPS for testing customer accounts. |
npx shopify hydrogen link and env pull | Connect your project to a storefront in the Hydrogen channel and pull its environment variables. |
npx shopify hydrogen deploy | Deploys your build to Oxygen. |
The agent skills are new in 2026. Hydrogen ships 20 of them, one for each part of a storefront, from the cart and variant forms to analytics and Oxygen. Shopify's suggested first prompt is "Set up my store with Shopify." The agent then builds the home, collection, search, product, cart and account pages and adds analytics. Treat that result as a first draft. A developer still needs to review the code, the design and the tracking before launch.
What has changed in Hydrogen since 2024?
- November 22, 2024: React Router v7 became stable as the successor to Remix.
- May 21, 2025: Hydrogen 2025.5.0 moved from Remix 2 to React Router 7.
- 2025 to April 2026: quarterly releases (2025.7, 2025.10, 2026.1, 2026.4) followed the new API versions and added cart features such as gift card codes and delivery addresses. Hydrogen 2026.4.0 made the Storefront API proxy mandatory and moved consent tracking to cookies set by the server.
- June 17, 2026: Shopify released the developer preview of the framework-agnostic Hydrogen.
- August 2026: Oxygen opened to development stores (August 3) and trial plan stores (August 25). On August 5, Shopify added WebMCP tools to Liquid and Hydrogen storefronts, so AI agents in supported browsers can search the catalog and manage the cart.
- October 14, 2026: Hydrogen 2026-10 became generally available, with React Router and Next.js starters, React and Vue bindings and agent skills.
Storefronts on Hydrogen 2026-04 or earlier keep working, and Shopify says there is nothing you need to do today. The 2026.4 line was still getting patch releases in October 2026. Shopify recommends migrating and publishes a migration guide, plus a migration skill for coding agents. If a storefront still runs on Remix, the move to React Router 7 is part of that migration.
One practical warning: a caret range such as ^2026.4.0 in package.json can install 2026-10, which has breaking changes. Use a tilde range such as ~2026.4.0 until you are ready to migrate.
Is Hydrogen worth it, or is a Shopify theme the better choice?
For most stores, a theme is the better choice. Shopify's own docs say that a headless storefront "costs more to build and run than a theme." They recommend headless when you need something that "can't be achieved with Shopify's sales channels, themes, and apps," or when your web stack does not use Liquid.
| Factor | Shopify theme (Liquid) | Hydrogen (headless) |
|---|---|---|
| Cost | Lower. You pay for the theme and the setup. Hosting is part of your Shopify plan. | Higher. You pay for a custom frontend and for developers to keep it running. Oxygen is included in paid plans; other hosts bill separately. |
| Speed to launch | Faster. The Online Store, the theme editor and app blocks are ready to use. | Slower. Our headless projects with a custom design usually take around 9 to 10 weeks. |
| Flexibility | Good within the theme structure: sections, blocks, metafields and the theme editor. | Full control over layout, interactions, routing, data sources and the design system. |
| Apps | Most App Store apps install in a few clicks, many through theme app blocks. | Theme app blocks do not apply. Each app needs an API, an SDK or support for Shopify's standard storefront actions, and some need custom work. |
| Maintenance | Low. Shopify hosts and serves the storefront. You update the theme when you choose. | Ongoing. You own the code, the framework and Hydrogen upgrades, API version changes, and SEO basics such as sitemaps and meta tags. |
| Content editing | Your team edits pages in the theme editor. | Depends on what you build: metaobjects, a headless CMS or custom tools. |
When Hydrogen is worth it
- Your design or interactions do not fit a theme without heavy workarounds, for example product configurators or editorial layouts.
- Your storefront pulls data from several systems, such as a headless CMS, a PIM, a search service or your own APIs.
- You already run a React or Vue frontend. Since 2026-10, you can add Hydrogen to an existing Next.js or React Router app instead of rebuilding it.
- You serve several brands, markets or channels from one codebase.
- You have developers, in-house or at an agency, to look after the storefront after launch.
When a theme is the better choice
- You are launching a new store or still testing the product.
- Your team edits pages and campaigns on its own and relies on the theme editor.
- Your store depends on many App Store apps that plug into the theme.
- Speed is your main goal. A well-built theme can be fast, and a headless build does not fix a slow store on its own.
- You want your store to work with AI shopping agents. Since August 2026, Liquid storefronts get WebMCP tools too, so this alone is no reason to go headless.
How do we use Hydrogen on client projects?
We build headless storefronts for clients on Hydrogen and Remix. One example is Carl Friedrik, a brand of leather travel accessories. They moved to Shopify Plus, and we rebuilt their storefront headless on Hydrogen and Remix. The reasons were specific: the old setup was hitting limits on product variants and carried the weight of too many third-party apps. Today one headless stack runs both their direct-to-consumer store and a B2B portal with role-based pricing.
Before any Hydrogen build, we plan four things:
- Apps. List every app the store uses. Reviews, subscriptions, search and loyalty each need a headless-ready integration or custom work.
- SEO. Sitemaps, canonical URLs, structured data and meta tags are your code now. Hydrogen 2026-10 removed its sitemap and SEO helpers, so you write them yourself.
- Editing. Give the marketing team a way to change content without a developer, through metaobjects or a headless CMS.
- Upkeep. Shopify releases a new API version every quarter. Budget time to upgrade at least once a year.
If you are weighing a headless build, our Shopify headless development service starts with a review of your current store and an honest answer on whether headless makes sense. For Hydrogen projects, including moves to Hydrogen 2026-10, see Shopify Hydrogen development. If a theme is the better fit, we also build custom Shopify themes.
FAQ
Is Shopify Hydrogen free?
Yes. The Hydrogen package is open source under the MIT license, and Oxygen hosting is included at no extra charge on paid Shopify plans. The real cost is development, because a custom storefront needs developers to build and maintain it.
Do you need Shopify Plus to use Hydrogen?
No. Oxygen is available on paid plans from Starter to Plus. Since August 2026, development stores and trial plan stores can also deploy to Oxygen for testing.
Is Hydrogen still built on Remix?
No. Hydrogen moved from Remix 2 to React Router 7 in version 2025.5.0, in May 2025, after Remix merged into React Router. Since 2026-10, Hydrogen is a library that works with React Router 7, Next.js and other frameworks.
Can you use Hydrogen with Next.js?
Yes, since Hydrogen 2026-10. Vercel maintains Vercel Shop, a Next.js storefront built on Hydrogen that deploys to Vercel. It connects to your store through the Headless channel.
Do Shopify apps work with a Hydrogen storefront?
Some do, some do not. Apps that add features through theme app blocks are built for Liquid themes. On Hydrogen, an app needs an API, an SDK or support for Shopify's standard storefront actions. Check every app you depend on before you go headless.
Is Hydrogen better for SEO than a theme?
Not by default. Hydrogen storefronts render on the server, so search engines can read them, but you build sitemaps, meta tags and structured data yourself. A fast, well-structured theme can rank just as well. Choose Hydrogen for flexibility, not for SEO alone.
Going headless with Hydrogen?
We design and ship Hydrogen storefronts that hold their performance under real traffic.
Shopify insights, straight to your inbox
Practical notes on growing a Shopify store: conversion, speed, migrations, and what we learn from client builds.
Want more of our posts in your Google results? Add Codersy as a preferred source.
Add Codersy on Google(opens in a new tab)