Hydrogen

Hydrogen (@shopify/hydrogen) is Shopify's toolkit for building headless storefronts in the JavaScript framework you already use. It ships with agent skills that teach coding agents how to use it.

Documentation · API reference · Changelog

Note

This README covers Hydrogen 2026-10 or later. Hydrogen 2026-04 and earlier are on the 2026-04 branch, with docs in Legacy Hydrogen. To migrate a storefront, follow Migrate to the latest version of Hydrogen.

What's included

Storefront API client: typed gql() queries, caching, and typed errors.
Request handlers: the routes a Shopify storefront needs, such as the Storefront API proxy, /api/cart, checkout and cart permalinks, URL redirects, and the MCP endpoints for agents.
Cart: server handlers, HTML forms that work before JavaScript loads, and a store that shows line changes before the server responds.
Products and collections: variant selection, collection filters, sorting, and pagination.
Predictive search: a search store with server handlers and form helpers.
Money: formats Shopify MoneyV2 amounts for the buyer's locale and currency.
Markets: country and language context for Shopify Markets.
Analytics: Shopify storefront analytics with consent handling.
Shop Pay: Shop Pay buttons.
Customer accounts: the Customer Account API client, login and logout handlers, and sessions.

Get started

You need a Shopify store with Storefront API access from the Headless channel. Until you connect one, the template and the setup skill fall back to mock.shop, a public Storefront API with demo data.

Deploy a template

React Router on Oxygen. Shopify's starter template, templates/react-router, deployed to Oxygen from your Shopify admin.

Next.js on Vercel. Vercel Shop is a Next.js storefront built on Hydrogen and maintained by Vercel.

Add Hydrogen to your project

From your project's root directory, run:

npx @shopify/hydrogen@latest setup

setup installs @shopify/hydrogen with your project's package manager, and copies Hydrogen's agent skills into .claude/skills (read by Claude Code) and .agents/skills (read by Codex, Cursor, and OpenCode), matched to the installed version. In an empty directory, it offers to create a project from the React Router template.

Then ask your coding agent to build the storefront:

Set up my store with Shopify.

The agent follows the hydrogen-setup skill. It adds a Storefront API client and request handlers, then builds a home page, collection and search pages, a product page, a cart page and cart drawer, an account page, and consent-gated analytics. It runs your typecheck after each step and smoke-tests the storefront at the end.

After you upgrade Hydrogen

Skills describe the API of the installed version, so sync them after each upgrade:

npx @shopify/hydrogen skills sync

npx @shopify/hydrogen skills check exits non-zero when the skills are out of date, so you can run it in CI. See Keeping skills in sync.

How it works

Hydrogen has a framework-independent core, plus bindings for React and Vue:

Entry point	Contains
`@shopify/hydrogen`	The core. It includes the Storefront API client, `gql`, request handlers, route templates, money formatting, analytics, Shop Pay, caching, and the stores for the cart, product form, collections, and predictive search.
`@shopify/hydrogen/react`	React components and hooks built on the core, such as `createCartComponents()`, `createProductComponents()`, `ShopifyScripts`, and `ShopPayButton`.
`@shopify/hydrogen/vue`	The same components for Vue, with composables in place of hooks.

The package has three more entry points:

@shopify/hydrogen/customer-account: the Customer Account API client and customer session helpers.
@shopify/hydrogen/vite: a Vite plugin for trusted local HTTPS during development.
@shopify/hydrogen/ts-plugin: a TypeScript plugin that flags unknown fields in gql() queries in your editor.

On the server, the request handlers run before your framework's router. handleShopifyRoutes() answers the routes that Hydrogen owns and passes every other request to your router. When your router returns a 404, handleShopifyRedirects() checks the store's URL redirects.

In the browser, state that changes while a customer is on the page lives in observable stores: the cart, the product form's selected variant, collection filters, and predictive search results. Each store has getState() and subscribe(listener), and the listener receives the full state on every change. The React and Vue bindings wrap the stores in hooks and composables. The cart, collection, and predictive search hooks take a selector, so a component updates only when the selected value changes:

import { createCartComponents } from "@shopify/hydrogen/react";
import type { cartHandlers } from "./cart-handlers"; // your cart server handlers

export const { CartProvider, useCart } = createCartComponents<typeof cartHandlers>();

function CartCount() {
  const totalQuantity = useCart((cart) => cart.data.totalQuantity);
  return <span>{totalQuantity}</span>;
}

Hydrogen emits and handles Shopify's standard storefront events and actions, the same ones that Liquid themes use. Apps can integrate with a Hydrogen storefront the same way they integrate with a theme, and the cart store applies shopify:cart:* events from any source, including apps and agents that call Standard Actions. Cart changes need Shopify's runtime scripts on the page: render ShopifyScripts in React or Vue, or use renderShopifyScriptTags() in other frameworks.

Query the Storefront API

Create a Storefront API client for each request, in server code. getBuyerIp() is yours to implement: return the buyer's IP address from a header that your host sets.

import {
  createShopifyRequestContext,
  createStorefrontClient,
  gql,
} from "@shopify/hydrogen";

const storeDomain = process.env.PUBLIC_STORE_DOMAIN;
const privateStorefrontToken = process.env.PRIVATE_STOREFRONT_API_TOKEN;
if (!storeDomain || !privateStorefrontToken) {
  throw new Error("Set PUBLIC_STORE_DOMAIN and PRIVATE_STOREFRONT_API_TOKEN.");
}

const storefront = createStorefrontClient({
  type: "private",
  requestContext: createShopifyRequestContext({
    request,
    i18n: { country: "US", language: "EN" },
    buyerIp: getBuyerIp(request.headers),
  }),
  config: { storeDomain, privateStorefrontToken },
});

const { data } = await storefront.graphql(
  gql(`
    query Home {
      products(first: 3) {
        nodes { handle title }
      }
    }
  `),
);

data is typed from the Storefront API schema that ships with Hydrogen. To check queries in your editor and in CI, see GraphQL tooling.

Frameworks and runtimes

Hydrogen works in any JavaScript framework that renders on the server. Frameworks without a packaged binding use the core directly.

Framework	Uses	Starter or example
React Router	`@shopify/hydrogen/react`	`templates/react-router` (starter)
Next.js	`@shopify/hydrogen/react`	Vercel Shop (starter), `examples/nextjs`
Nuxt	`@shopify/hydrogen/vue`	`examples/nuxt`
Astro	`@shopify/hydrogen`	`examples/astro`
SvelteKit	`@shopify/hydrogen`	`examples/sveltekit`
SolidStart	`@shopify/hydrogen`	`examples/solid-start`

The projects in examples/ test Hydrogen across frameworks. They aren't starters and aren't versioned for reuse.

The core depends on web platform APIs (fetch, Request, Response, and Web Crypto) rather than on a specific runtime. It targets Oxygen, Node.js, Cloudflare Workers, Deno, and other runtimes that provide those APIs, including Vercel's. The template and examples in this repository run on Oxygen and Node.js. See About deploying Hydrogen storefronts, and before you go live, work through the production checklist.

Agent skills

setup and skills sync copy these skills into your project. Each skill covers one part of a storefront:

Setup and verification: hydrogen-setup, hydrogen-smoke-test
Data and requests: hydrogen-storefront-client, hydrogen-request-handlers, hydrogen-routing, hydrogen-markets
Cart: hydrogen-cart-ui, hydrogen-cart-drawer, hydrogen-cart-metafields
Products, collections, and search: hydrogen-variant-form, hydrogen-collection-browser, hydrogen-predictive-search, hydrogen-image, hydrogen-money
Checkout, accounts, and analytics: hydrogen-shop-pay, hydrogen-customer-account, hydrogen-analytics
Hosting and local development: hydrogen-oxygen, hydrogen-local-https
Migration from classic Hydrogen: migrate-to-hydrogen-2026-10

Read them in packages/hydrogen/skills.

Versioning

Hydrogen 2026.10.x uses version 2026-10 of the Storefront API and the Customer Account API. Hydrogen 2026-04 and earlier are also published as @shopify/hydrogen, so a caret range such as ^2026.4.0 can resolve to 2026-10. To stay on a version, use a tilde range, such as ~2026.4.0.

Packages

Package	Description
`@shopify/hydrogen`	The Hydrogen toolkit and its agent skills.
`@shopify/mini-oxygen`	A local Oxygen runtime and Vite plugin, for developing and previewing storefronts that deploy to Oxygen.

Help

Report bugs in Issues, and report security vulnerabilities through Shopify's bug bounty program.

License

MIT