The Shopify Hydrogen storefront framework is built on Remix and Vite, with Shopify-specific utilities layered on top — createStorefrontClient for typed Storefront API calls, built-in cache headers with stale-while-revalidate semantics, useCart for cart state, and an integrated analytics system. This guide covers the complete Shopify Hydrogen storefront architecture from initial setup to Oxygen deployment, including the cache strategy decisions that most affect performance. Our full headless commerce architecture guide covers when to choose Hydrogen over a custom stack.

Shopify Hydrogen storefront — Storefront API integration, React Server Components, cart management and Oxygen edge deployment by CodeAtoZ

The Shopify Hydrogen storefront uses createStorefrontClient to create a typed GraphQL client connected to the Shopify Storefront API. Data fetching happens in Remix loaders — server-side functions that run before the component renders. The framework automatically attaches the correct Cache-Control headers based on the cache strategy you set, enabling CDN caching at Oxygen’s edge without any manual header management.

// app/routes/products.$handle.tsx
import {json} from '@shopify/remix-oxygen';
import {useLoaderData} from '@remix-run/react';

export async function loader({params, context}: LoaderArgs) {
  const {product} = await context.storefront.query(PRODUCT_QUERY, {
    variables: {handle: params.handle},
    cache: context.storefront.CacheLong(), // cache for 1hr, SWR 24hr
  });
  if (!product) throw new Response('Not found', {status: 404});
  return json({product});
}

const PRODUCT_QUERY = `#graphql
  query Product($handle: String!) {
    product(handle: $handle) {
      title handle priceRange {minVariantPrice {amount currencyCode}}
      images(first: 6) {nodes {url altText width height}}
      variants(first: 100) {nodes {id title availableForSale selectedOptions {name value}}}
    }
  }`;

Cache strategy is the most performance-critical decision in a Shopify Hydrogen storefront. Hydrogen provides four built-in strategies: CacheNone() for real-time data (cart, account), CacheShort() for data that changes frequently (inventory, pricing — 1 min TTL, 10 min SWR), CacheLong() for slow-changing data (product descriptions, images — 1hr TTL, 24hr SWR), and CacheCustom() for explicit control. Every Remix loader that calls the Storefront API should explicitly set a cache strategy. Product pages use CacheLong(), collection pages use CacheShort(), and anything cart-related uses CacheNone(). The Hydrogen caching documentation covers the full strategy API.

The Shopify Hydrogen storefront cart is managed via the Storefront API cartCreate, cartLinesAdd, and cartLinesUpdate mutations, with cart ID persisted in a cookie. Hydrogen provides the CartProvider and useCart hook to manage cart state client-side. Deploy to Oxygen with shopify hydrogen deploy — Shopify hosts the Shopify Hydrogen storefront on its global CDN via V8 isolates, with automatic SSL, domain management, and performance monitoring included. Alternatively, deploy to Vercel, Netlify, or Cloudflare Workers if you need more infrastructure control. Our headless commerce team builds and deploys Hydrogen storefronts. See the Remix documentation for the full routing and loader API for Shopify merchants needing custom checkout and performance optimisation. See also the official Hydrogen documentation.