# Shopify Hydrogen: Building Headless Commerce in 2026

By [Eoin Villarin](https://amvprosox.com/about). Published 2026-03-20, updated 2026-10-28. Canonical: https://amvprosox.com/blog/shopify-hydrogen-headless-commerce-2025

> Hydrogen is now a framework-agnostic Shopify library. Learn when headless beats a Liquid theme, how the 2026-10 architecture works, the SEO essentials and where to deploy.

## What is Shopify Hydrogen in 2026, and when is headless commerce worth it?

Shopify Hydrogen 2026-10, generally available since October 14, 2026, is a framework-agnostic JavaScript library that adds cart, Markets pricing, analytics and checkout handoff to any framework that runs server code, including Next.js. Headless is worth it for custom UX, content-led storefronts or commerce inside an existing app; for most other stores a fast Liquid theme is the smarter choice.

**Key takeaways**

- Shopify offers two starters: a React Router template for Oxygen and Vercel Shop, a Next.js storefront maintained by Vercel.
- Install Hydrogen in an existing project by running npx @shopify/hydrogen@latest setup, which requires Node.js 22 or 24.
- Shopify says Oxygen hosting remains free and has been available on development and trial plan stores since August 2026.
- Shopify supports each stable Storefront API version for at least 12 months and releases a new version every quarter.
- Legacy Hydrogen means versions 2026-04 and earlier; existing storefronts keep working and migration is optional for now.

**Shopify Hydrogen** changed more in 2026 than in any year since it launched. Until this year, Hydrogen was a full framework: if you wanted its cart, analytics or customer account helpers, you built your whole storefront on it. On October 14, 2026, Shopify made Hydrogen 2026-10 generally available as a framework-agnostic JavaScript library that adds commerce to the stack you already use.

That shift matters for anyone weighing headless commerce. You can now keep a Next.js or React Router codebase, add Hydrogen for cart, pricing and checkout handoff, and deploy to Oxygen, Vercel or another host. It also raises a fair question: when is a headless storefront worth it over a well-built Liquid theme?

This guide covers what the new Hydrogen does, when headless makes sense, how the architecture fits together, how to start a store, what to watch for SEO and speed, where to deploy, and how to handle a legacy Hydrogen project.

## What is Shopify Hydrogen in 2026?

According to the [Hydrogen 2026-10 announcement](https://shopify.dev/changelog/blog/hydrogen-2026-10-is-now-available), Hydrogen now works with any JavaScript framework that runs server code. Your framework still owns routing, data loading and rendering. Hydrogen owns the commerce layer.

- **Cart:** add, update and remove lines, cart attributes and the handoff to Shopify Checkout.

- **Product and collection logic:** variant selection, collection filters and predictive search.

- **Markets pricing:** prices in the buyer's currency for international stores.

- **Analytics and consent:** consent-aware analytics with page view events on every navigation.

- **Shop Pay and customer accounts:** the Shop Pay button and Customer Account API helpers.

Shopify provides two starters: a React Router template that deploys to Oxygen from your Shopify admin, and Vercel Shop, a Next.js storefront built on Hydrogen and maintained by Vercel. The release also ships around 20 skills that teach coding agents the Hydrogen API version installed in your project.

## Hydrogen vs a Liquid theme: when does headless make sense?

Headless is not an upgrade by default. It is a trade: more control and flexibility in exchange for more code to build, host and maintain. For most small and mid-sized stores, a fast Online Store 2.0 theme is still the better investment.

![Teal and red gears meshing in a transmission, like a framework and commerce layer working together](https://amvprosox.com/api/img/1793146649820-cgut5e)
*Your framework renders pages; Hydrogen handles the commerce layer. Photo: rawpixel, CC0*

| Factor | Liquid theme | Hydrogen storefront |
| --- | --- | --- |
| Build effort | Low to medium, theme editor for content | Medium to high, developer-owned codebase |
| Merchant editing | Theme editor sections and blocks | Needs a CMS or Shopify metaobjects wired in |
| App compatibility | Most theme app extensions work directly | Apps need API-based integrations |
| Custom UX | Limited by theme architecture | Anything React or your framework can do |
| Hosting | Included with Shopify | Oxygen (free) or your own platform |
| Checkout | Shopify Checkout | Shopify Checkout |

Headless tends to earn its cost when you have one or more of these: a content-heavy brand site with a separate CMS, a product configurator or complex bundling UI, several storefronts sharing one codebase, or an existing React app that needs commerce added. If your main goal is a faster store, start with my [Shopify speed optimization checklist](https://amvprosox.com/blog/shopify-speed-optimization-2026) before rebuilding anything.

Note the last row of the table. Both approaches hand buyers to Shopify Checkout. Checkout customization works through Checkout Extensibility either way, which I cover in my guide to [Shopify checkout UI extensions](https://amvprosox.com/blog/shopify-checkout-extensibility-ui-extensions-guide).

## How does the new Hydrogen architecture work?

The mental model is simple once you separate responsibilities. Requests reach your server, Hydrogen's request handlers run first, and then your framework's router takes over.

- **Hydrogen request handlers** deal with commerce routes, such as cart permalinks in the `/cart/{variantId}:{quantity}` format that redirect to checkout, and Shopify URL redirects after a 404.

- **Your router** renders home, collection, product, search, cart and account pages using its own conventions.

- **The Storefront API client** runs on the server and queries products, collections and carts with GraphQL.

- **Client components** receive data as props and use Hydrogen's cart and product bindings for interactivity.

### Storefront API versions and tokens

Hydrogen 2026-10 targets Storefront API version 2026-10. Shopify releases a new API version every quarter and supports each stable version for at least 12 months, according to its [API versioning policy](https://shopify.dev/docs/api/usage/versioning). Put a recurring upgrade in your maintenance plan rather than waiting for a deprecation email.

Keep the private Storefront API token on the server only. Read environment variables in server code and pass plain values to client components as props, never the token itself.

## How to start a Shopify Hydrogen storefront

You have two paths: deploy a template, or add Hydrogen to an existing project. Both require Node.js 22 or 24 and a framework that runs server code.

![Open notebook of app wireframes beside a laptop, planning product pages before real data](https://amvprosox.com/api/img/1793146651080-65nl29)
*Start with mock data, then connect your real store. Photo: rawpixel, CC0*

- **Pick your path.** For a new store, deploy the React Router template to Oxygen or clone Vercel Shop for Next.js. For an existing app, run the setup command in your project root.

- **Install Hydrogen.** Run `npx @shopify/hydrogen@latest setup`. It installs the package with your package manager and adds agent instructions without touching app code.

- **Configure environment variables.** Start with demo data from mock.shop, then add your store domain, private Storefront API token, session secret and Customer Account API client ID.

- **Wire the request handlers** before your router and share the Storefront API client with your loaders or server components. Next.js projects need `cacheComponents: true`.

- **Build pages in order:** home, collection and search, product, cart, analytics, cart drawer, then customer accounts.

- **Type check your queries.** Add `hydrogen gql check` to your typecheck script so broken GraphQL fails the build.

Your product page query is plain Storefront API GraphQL. The `@inContext` directive returns prices for the buyer's market:

```
query ProductPage($handle: String!, $country: CountryCode)
@inContext(country: $country) {
  product(handle: $handle) {
    id
    title
    descriptionHtml
    seo { title description }
    featuredImage { url altText width height }
    variants(first: 10) {
      nodes {
        id
        availableForSale
        price { amount currencyCode }
      }
    }
  }
}
```

If you are building the storefront in Next.js, the same App Router patterns apply as on any other project. My [Next.js App Router migration guide](https://amvprosox.com/blog/nextjs-15-app-router-migration-guide) covers async params, caching and metadata in Next.js 16.

## SEO and performance for a headless Shopify storefront

A Liquid theme gives you sitemaps, canonical tags and structured data out of the box. On a headless build, you own all of it. These are the items I check on every Hydrogen launch:

- **Server rendering:** product, collection and content pages must return full HTML, not a client-side shell.

- **Metadata from Shopify:** map each product's `seo.title` and `seo.description` into your framework's metadata API so merchants can still edit them in the admin.

- **Canonicals and hreflang:** one canonical per product, with alternate links per market and language for international stores.

- **Product structured data:** output Product JSON-LD with name, image, price, currency and availability, following [Google's product structured data guidelines](https://developers.google.com/search/docs/appearance/structured-data/product).

- **Redirects and 404s:** let Hydrogen's handler check Shopify URL redirects after a 404 so old links keep working.

- **Sitemap:** generate it from the Storefront API and include every indexable product, collection and page.

For speed, the biggest wins are usually the same as on any React site: serve a static or cached shell, stream personalized parts, size images correctly, and keep client JavaScript small. Cache catalog queries that change rarely and keep cart and customer data uncached.

> Headless does not make a store fast by itself. A careless Hydrogen build can ship more JavaScript than a good Liquid theme. Speed comes from what you render on the server and what you refuse to send to the browser.

## Where should you deploy: Oxygen, Vercel or elsewhere?

Hydrogen can be hosted anywhere your framework runs. In practice there are three common choices.

![Glowing blue globe showing North America, a reminder that hosting reaches shoppers worldwide](https://amvprosox.com/api/img/1793146652345-3p3j74)
*Choose hosting based on your framework and team, not hype. Photo: rawpixel, CC0*

- **Oxygen:** Shopify's hosting for Hydrogen, based on Cloudflare's open-source workerd runtime. Shopify says it remains free, and since August 2026 it is available on development and trial plan stores. Development store deployments always require a store login, because those stores have no public environments.

- **Vercel:** the natural home for the Vercel Shop Next.js starter, with preview deployments per branch.

- **Your own platform:** any Node.js host or edge platform your framework supports, useful when the storefront is part of a larger app.

Oxygen is the simplest choice for the React Router starter because deployments, environments and storefront settings live in the Shopify admin. Vercel or another host makes more sense when the store is one part of a bigger Next.js app your team already deploys.

## How to migrate a legacy Hydrogen storefront

Shopify now calls Hydrogen 2026-04 and earlier "legacy Hydrogen". Those versions are the framework-based releases, which moved from Remix to React Router 7 during 2025. Shopify states that existing storefronts keep working as they do now and that migration is optional for the moment.

When you are ready, the migration keeps your pages and routes and changes where the commerce code comes from. Shopify publishes a `migrate-to-hydrogen-2026-10` skill in the Hydrogen GitHub repository to guide a coding agent through it. My approach is the same as any framework upgrade: branch, migrate the cart first, compare analytics events and checkout handoff against production, then move the remaining pages.

This is also a good moment to look at agent-driven shopping. Hydrogen 2026-10 uses the same standard storefront actions as Liquid themes, so agents in WebMCP-capable browsers can search the catalog and update the cart. I explain the wider picture in my post on [agentic commerce on Shopify](https://amvprosox.com/blog/shopify-agentic-commerce-chatgpt).

## Frequently asked questions

### Is Shopify Hydrogen free to use?

Yes. Hydrogen is a free library, and Shopify says Oxygen hosting remains free for Hydrogen storefronts. Your real costs are development time, ongoing maintenance and any third-party services such as a CMS, search or hosting outside Oxygen. You still need a Shopify plan for the store itself.

### Do I have to use React Router or Remix with Hydrogen now?

No. Since Hydrogen 2026-10, it works with any JavaScript framework that runs server code, including Next.js. Shopify offers a React Router starter for Oxygen and points Next.js users to Vercel Shop. Legacy Hydrogen versions 2026-04 and earlier were built on React Router, and earlier still on Remix.

### Is a headless Shopify store better for SEO?

Not automatically. A headless store can rank as well as a Liquid theme if it renders HTML on the server and outputs correct metadata, canonicals, sitemaps and structured data. But you must build all of that yourself, so a careless headless launch often performs worse than a well-built theme.

### Can I keep my Shopify apps on a Hydrogen storefront?

Some, not all. Apps that work through APIs, checkout extensions or the Customer Account API usually work. Apps that inject code into Liquid themes or rely on theme app extensions do not, so audit every app before committing to headless and budget for replacements or custom integrations.

## Is Shopify Hydrogen right for your store?

Shopify Hydrogen is now a commerce library rather than a framework you must adopt wholesale, which makes headless far more practical. Choose it when you need custom UX, a content-led storefront or commerce inside an existing app, and plan for SEO, analytics and maintenance from the start. For most other stores, a fast Liquid theme remains the smarter choice.

I build and maintain Shopify stores for brands worldwide, including Shopify Plus projects like [Real Mad Honey](https://amvprosox.com/case-studies/realmadhoney). If you want an honest recommendation on headless versus theme for your store, [contact me through my contact form](https://amvprosox.com/#contact-form) or browse more [Shopify and web case studies](https://amvprosox.com/case-studies).