Hydrogen in 2026: React Router, Hydrogen React, and Storefront API Versioning

Headless Shopify is no longer “Remix + a bag of fetch calls.” Official docs for the 2026-04 line are clear: Hydrogen is built on React Router. The commerce primitives — ShopPayButton, cart helpers, buyer identity — come from Hydrogen React, a framework-agnostic package that Hydrogen re-exports.

Import from the right package

If you are building a Hydrogen app, import from @shopify/hydrogen, not deep imports from @shopify/hydrogen-react, unless you are embedding commerce UI in a non-Hydrogen React app. Hydrogen re-exports the React package so version alignment stays one line in package.json.

import { ShopPayButton } from '@shopify/hydrogen';

Versioning is not optional

Hydrogen React is tied to a quarterly Storefront API version. Hydrogen 2026.4.x pairs with Storefront API 2026-04. If that API release has breaking changes, the matching Hydrogen React release has the same breaks. We pin both and treat upgrades as a planned sprint, not a drive-by npm update.

Auth pattern we use

createStorefrontClient from Hydrogen React takes storeDomain and tokens. Public token headers are fine in the browser. Private tokens stay on the server — getPrivateTokenHeaders() on a server query, never in client bundles. Environment variables follow PUBLIC_STORE_DOMAIN, PUBLIC_STOREFRONT_API_TOKEN, and PRIVATE_STOREFRONT_API_TOKEN.

Sources: Hydrogen 2026-04, Hydrogen React 2026-04.