Hydrogen

Why it matters

The argument for Hydrogen over a generic React framework is that commerce has a long list of solved problems you would otherwise re-solve badly. Cart state that survives navigation and stays consistent across tabs, optimistic updates that reconcile with server truth, variant selection that maps cleanly to URLs, analytics events in the shape Shopify expects — each is a week of work and a source of subtle bugs.

The argument against is lock-in of a mild kind. Hydrogen is opinionated about framework and deployment, and a team with strong existing conventions in another stack may find those opinions cost more than the primitives save.

For most headless Shopify builds, the primitives win. The teams that regret it are usually the ones who needed a headless build less than they thought.

How it works on Shopify

Hydrogen is a React framework built on Remix, distributed as a starter template rather than a black box — you get a real repository you own and modify.

It ships a typed Storefront API client with the schema wired in, so queries are checked at build rather than discovered at runtime. Around that sit the commerce primitives: cart hooks and actions, product and variant helpers, money and image components that handle formatting and responsive sizing, and analytics hooks that emit the events Shopify's reporting expects.

Server-side rendering is the default, with caching handled per route. Getting those cache directives right is most of the performance work on a Hydrogen storefront.

Deployment is normally to Oxygen, which is included with a Shopify plan and handles preview environments per branch. Hosting elsewhere is possible but forfeits that integration.

Customer accounts, subscriptions, and B2B each have their own APIs to wire in — they are not included by rendering a product page.

Common mistakes

• Rebuilding the cart. The cart primitives handle inventory errors, discount recalculation, and race conditions between tabs. Hand-rolled versions handle the happy path.
• Ignoring caching. A Hydrogen route with no cache strategy re-queries the Storefront API on every request and is slower than the Liquid theme it replaced.
• Assuming apps carry over. Reviews, upsells, and popups injected into a Liquid theme do not exist here. Each needs an API integration or a replacement.
• Treating the starter as a framework. It is your code. Upgrades are merges you perform, not updates that arrive.
• Forgetting the checkout handoff. Checkout remains Shopify's. The storefront's job ends at the cart, and the transition between them needs designing.

When you need help

Before the build, the honest question is whether a Hydrogen storefront is warranted at all — the assessment described under headless commerce applies unchanged, and it frequently concludes that a well-built Liquid theme is the better answer.

Once committed, the parts worth not learning in production are the data layer and the caching strategy. Query shape, cache directives per route, and how cart state is held decide whether the storefront is fast, and they are difficult to retrofit once the site is live and the patterns have spread through the codebase.