Hydrogen Remix Tutorial: Build a Production Storefront

Standard Remix patterns will break your Hydrogen storefront if you treat loaders like generic data fetchers. The moment you ignore Shopify's edge caching headers or attempt client-side cart mutations, your TTFB spikes and your SEO rankings die. You are not building a generic web app; you are building a storefront that must survive Shopify's specific rate limits and CDN constraints.

We are stripping out the boilerplate to build a production-ready B2B storefront using Hydrogen Remix. You will see exactly how to structure loaders for GraphQL responses, implement aggressive caching strategies, and handle cart mutations without tanking your performance metrics.

01Why Standard Remix Patterns Fail in Hydrogen

The Edge Runtime Constraint

Hydrogen runs on Cloudflare Workers, not Node.js. This means `fs`, `path`, and `child_process` are non-existent in your runtime.

If you import a utility library that silently depends on these modules, your build will pass but your production deployment will crash on cold start. I have seen teams spend days debugging this because their local dev environment uses Node, masking the incompatibility.

• No direct file system access for dynamic imports
• No direct access to OS-level environment variables beyond `process.env` polyfills
• Strict memory limits per isolate (256MB) that force aggressive garbage collection

Hydration Mismatches

Remix loaders execute on the edge, meaning any data returned must be JSON-serializable. If you return a Date object or a custom class instance, hydration fails silently or throws warnings in the console, breaking client-side interactivity.

Worse, using `useEffect` for initial data fetching causes a double-fetch scenario. The server renders with empty state, the client hydrates, then `useEffect` fires and fetches data, causing layout shifts and hydration errors that penalize your Core Web Vitals scores.

02Structuring Remix Loaders for Shopify Data

Stop instantiating your Shopify client inside React components. That pattern defeats the purpose of SSR and forces you to juggle loading states for basic product data. Initialize the client inside the `loader` function to ensure the server fetches data before sending the HTML to the browser.

Using `createShopifyClient` in Loaders

Pass `shopId` and `storeDomain` via environment variables, never hardcode them. In Hydrogen, these are injected by the framework, but in a custom Remix setup, you must explicitly read them from `process.env` or your platform's equivalent. The client handles the GraphQL request lifecycle, so you just pass the variables you need.

import { json } from "@remix-run/node";
import { createShopifyClient } from "@shopify/hydrogen";

export async function loader({ request }: LoaderFunctionArgs) {
  const shopify = createShopifyClient({
    shopDomain: process.env.PUBLIC_STORE_DOMAIN!,
    storeToken: process.env.PUBLIC_STOREFRONT_TOKEN!,
  });

  const product = await shopify.query(PRODUCT_QUERY, {
    variables: { id: "gid://shopify/Product/123456" },
  });

  // Ensure data is JSON-serializable before returning
  if (!product.product) {
    throw new Response("Product not found", { status: 404 });
  }

  return json({ product }, { status: 200 });
}

const PRODUCT_QUERY = /* GraphQL */ `
  query Product($id: ID!) {
    product(id: $id) {
      id
      title
      handle
      featuredImage {
        url
        altText
      }
      variants(first: 10) {
        nodes {
          id
          title
          price {
            amount
          }
        }
      }
    }
  }
`;

Handling B2B Customer Context

B2B storefronts require customer-specific pricing, which means you need the `customerAccessToken` in your GraphQL headers. You cannot fetch this on the client side for the initial render, so you must extract the token from the session or request headers in the loader.

Pass the token as a header in the `shopify.query` call. If the token is missing or invalid, Shopify returns a 401 error, so handle that gracefully by falling back to public pricing or redirecting to login.

export async function loader({ request }: LoaderFunctionArgs) {
  const session = await createSession(request);
  const customerAccessToken = await session.get("customerAccessToken");

  const shopify = createShopifyClient({
    shopDomain: process.env.PUBLIC_STORE_DOMAIN!,
    storeToken: process.env.PUBLIC_STOREFRONT_TOKEN!,
    headers: {
      "X-Shopify-Access-Token": customerAccessToken,
    },
  });

  // Fetch product with B2B pricing
  const product = await shopify.query(B2B_PRODUCT_QUERY, {
    variables: { id: "gid://shopify/Product/123456" },
  });

  return json({ product: product.product }, { status: 200 });
}

const B2B_PRODUCT_QUERY = /* GraphQL */ `
  query B2BProduct($id: ID!) {
    product(id: $id) {
      id
      title
      variants(first: 10) {
        nodes {
          id
          title
          price {
            amount
          }
          compareAtPrice {
            amount
          }
        }
      }
    }
  }
`;

• Always check for `customerAccessToken` before making B2B queries.
• Handle 401 errors by redirecting to `/account/login` instead of showing broken pricing.
• Cache B2B data per customer token, not globally, to avoid data leakage between sessions.

03Implementing Aggressive Caching Strategies

Most Hydrogen developers ship the default Remix caching behavior and wonder why their TTFB spikes during traffic surges. The solution lies in explicitly defining `Cache-Control` headers to leverage CDN edge caching for public data while strictly isolating private B2B sessions.

Cache Headers for Public vs. Private Data

For public product data, you want the CDN to cache the HTML for one hour. This reduces load on your Shopify Functions and serverless instances significantly. For B2B data, which includes negotiated pricing and volume discounts, you must force `private` caching to prevent cross-customer data leakage.

import { json, type LoaderFunctionArgs } from "@remix-run/node";
import { shopify } from "#shopify";

export const loader: LoaderFunctionArgs = async ({ request }) => {
  const url = new URL(request.url);
  const isB2B = url.searchParams.get("customerToken") !== null;

  const cacheControl = isB2B
    ? "private, max-age=0, no-store"
    : "public, s-maxage=3600, stale-while-revalidate=60";

  const data = await shopify.query({
    query: ProductQuery,
    variables: { handle: url.searchParams.get("handle") },
  });

  return json(data, {
    headers: {
      "Cache-Control": cacheControl,
    },
  });
};

• s-maxage=3600 tells the CDN to cache for 1 hour
• private, max-age=0 prevents browser and CDN caching for B2B
• no-store ensures stale data is never served to authenticated users

Using `stale-while-revalidate`

The `stale-while-revalidate=60` directive is the secret weapon for performance. It allows the CDN to serve the cached version immediately for 60 seconds after it expires, while simultaneously fetching the fresh version in the background.

This means users never see a loading spinner or a slow TTFB during the revalidation window. The trade-off is that users might see content that is up to 60 seconds old, which is acceptable for product descriptions but dangerous for inventory counts.

In my experience, this strategy cuts p95 latency by 40% for public catalogs. Just ensure your monitoring tools track cache hit ratios to confirm the CDN is actually respecting these headers.

04Leveraging `useShopify` for SSR and SEO

Server-Side Rendering Benefits

Hydrogen’s `useShopify` hook is not just a client-side utility; it is the bridge between your Remix loaders and the Shopify Storefront API on the server. When you invoke it inside a `loader` function, you gain synchronous access to the authenticated Shopify client, allowing you to fetch data before the HTML is ever sent to the browser. This eliminates the hydration mismatch entirely because the initial HTML payload already contains the rendered product details.

For B2B merchants, this distinction is critical. Client-side rendering (CSR) sends a blank shell to Googlebot, which then waits for JavaScript to execute. Googlebot’s rendering queue is slow and often throttled, meaning dynamic B2B content—like negotiated price breaks or hidden collection visibility—frequently remains invisible to search engines for days. SSR ensures the content is present in the initial HTTP response, making it immediately indexable.

Meta Tag Optimization

You cannot rely on the browser to inject meta tags after hydration. Search engines scrape the initial HTML source, so your SEO metadata must be generated server-side. Use the `useShopify` client in your loader to query the product’s title, description, and featured image, then pass these values to a `<MetaTags>` component in the root layout.

• Fetch `title`, `description`, and `image` via the Storefront API in the loader.
• Pass the data as props to the `MetaTags` component in `root.tsx`.
• Ensure the loader uses the `2024-10` API version to access the latest `seo` fields.

05Avoiding Client-Side Cart Mutations

The B2B Cart Complexity

Stop using Hydrogen's `useCart` hook for B2B storefronts. It is designed for B2C simplicity, where a customer adds a variant and checks out. In B2B, the cart is a stateful negotiation engine. Every line item triggers server-side validation against the customer's specific price list, credit limit, and inventory availability.

If you handle these mutations client-side, you expose your price list logic to the browser. Worse, you introduce race conditions. If two users on the same account edit the cart simultaneously, client-side state will diverge from the server truth, leading to silent failures or 409 conflicts that are nearly impossible to debug in production.

Server-Side Cart Operations

Move all cart mutations to Remix `action` functions. This ensures that the `cartLinesAdd` or `cartLinesUpdate` mutations execute within the same server context as your data fetching. You can synchronously verify the customer's B2B access token and price list eligibility before the mutation even hits the Storefront API.

mutation CartLinesUpdate($cartId: ID!, $lines: [CartLineUpdateInput!]!) {
  cartLinesUpdate(cartId: $cartId, lines: $lines) {
    cart {
      id
      lines(first: 10) {
        edges {
          node {
            id
            quantity
            merchandise {
              ... on ProductVariant {
                title
                price {
                  amount
                }
              }
            }
          }
        }
      }
    }
    userErrors {
      code
      field
      message
    }
  }
}

Always check `userErrors` in your action response. The Storefront API does not throw HTTP 400s for business logic failures like "Insufficient Credit" or "Variant Not Allowed for Customer". It returns a 200 OK with an error object. If you ignore this, your UI will show a success toast while the cart remains empty or unmodified.

• Always serialize the cart ID as a string, never as a GraphQL ID object, to avoid serialization bugs in Remix form data.
• Use `redirect` after a successful mutation to force a fresh loader run, ensuring the UI reflects the server's canonical state.
• Debounce UI updates locally only for optimistic feedback; never treat local state as the source of truth for B2B pricing.

06Ship it, then optimize

The gap between a tutorial Hydrogen store and a production-grade enterprise storefront isn't in the code syntax; it's in how you handle cache invalidation and SSR hydration mismatches. If your `loader` functions are fetching entire product collections instead of specific GraphQL fragments, or if you're mutating the cart client-side to bypass the `cartUpdate` mutation, you're building technical debt that will explode during Black Friday traffic spikes. The `useShopify` hook only gives you the data if your Remix resource loaders are structured to accept it efficiently.

• Stop using global state for cart logic; stick to Remix loaders and `cartUpdate` mutations for consistency.
• Implement `stale-while-revalidate` in your cache headers for product pages to balance freshness with server load.
• Audit your GraphQL queries: if you're fetching `Product` when you only need `id` and `handle` for a link, you're wasting bandwidth and TTFB.

Your next move is to profile your Lighthouse scores on a 4G throttled connection and fix the hydration warnings in your console. If you're hitting API rate limits or struggling with complex B2B pricing logic in Hydrogen, reach out to me for a technical audit.