15 · Hydrogen + React Router v7 + Oxygen

Esta sección es mayormente referencia. Brew Atlas no requiere un storefront Hydrogen para llegar al final del tutorial — la ruta principal del proyecto usa un theme OS 2.0 (sección 05 en adelante). Los bloques de referencia muestran el flujo canónico de Hydrogen para que lo tengas a mano cuando sí lo necesites.

Qué es y por qué existe

Cuando un comerciante necesita control total sobre el diseño y la experiencia del storefront — más del que permite un theme de Online Store 2.0 — tiene dos opciones: un theme altamente customizado con JavaScript propio, o un storefront headless. La ruta headless le da control completo sobre el HTML, el CSS, y el JavaScript del sitio. Puede usar cualquier framework, cualquier sistema de diseño, y puede componer datos de múltiples fuentes además de Shopify.

El precio de esa libertad es real: tienes que construir y mantener el carrito, gestionar el handoff al checkout de Shopify, resolver la autenticación de clientes con el Customer Account API, manejar el caché del catálogo, y asegurarte de que las métricas de performance sean competitivas con las de un theme nativo. Un theme OS 2.0 bien optimizado tiene de base años de trabajo de Shopify en performance. Un storefront headless empieza desde cero en esos frentes.

Hydrogen existe para reducir ese costo. Es el framework opinionado de Shopify para storefronts React: te da el cliente del Storefront API con caché integrado, componentes optimizados (<Money>, <Image>), manejo de sesión para el carrito, y una integración directa con Oxygen. No tienes que resolver esos problemas desde cero — pero sí tienes que entender el modelo de datos y el ciclo de vida de las requests.

Contexto de migración: de Remix a React Router v7

Si lees documentación de Hydrogen anterior a septiembre de 2025, vas a encontrar referencias a Remix: remix.config.ts, @remix-run/react, useLoaderData de @remix-run/react. Todo eso cambió.

En septiembre de 2025, el equipo de Remix finalizó la fusión de Remix con React Router v7. El resultado práctico: React Router v7 en modo framework ES la continuación de Remix. El proyecto Remix como entidad separada dejó de existir. Hydrogen migró a React Router v7 en esa misma ventana.

Para el desarrollador, el impacto es mínimo pero el cambio de imports es consistente:

• Antes (Hydrogen ≤ 2025.x): import { useLoaderData } from '@remix-run/react'
• Ahora (Hydrogen 2026.x): import { useLoaderData } from 'react-router'

El remix.config.ts se convirtió en react-router.config.ts. Los loader y action functions siguen siendo funciones del servidor, las rutas siguen estando en app/routes/, y useLoaderData sigue siendo el hook para acceder a los datos del loader. El 95% del código es idéntico; el 5% que cambia son los imports.

Si encontrás documentación o tutoriales que dicen “Hydrogen usa Remix” en 2026, están desactualizados. El CLI y los templates del 2026 no contienen nada de @remix-run/*.

Scaffold: crear un proyecto Hydrogen

El comando oficial es:

Desde ~/proyectos/shopify/brew-atlas/:

cd ~/proyectos/shopify/brew-atlas
npm create @shopify/hydrogen@latest
# Project name? brew-atlas-hydrogen
# Link a store? Y (pegar la URL de tu dev store)
# Install deps? Y

Esto crea el proyecto con la versión 2026.4.0 de Hydrogen y configura la conexión con tu Storefront API automáticamente.

Estructura del proyecto

# ~/proyectos/shopify/brew-atlas/brew-atlas-hydrogen/ (raíz del storefront headless)
app/
├── root.tsx                 # Root layout; <ShopifyProvider> configurado aquí
├── entry.server.tsx         # SSR entry; adaptador de Oxygen
├── routes/
│   ├── _index.tsx           # Página principal
│   ├── products.$handle.tsx # Página de detalle de producto (PDP)
│   ├── cart.tsx             # Carrito
│   └── account.tsx          # Área de cuenta (Customer Account API)
├── lib/
│   ├── fragments.ts         # Fragments de GraphQL reutilizables
│   └── session.server.ts    # Gestión de sesión para el carrito
└── graphql/
    └── codegen.ts           # Generación de tipos TypeScript desde queries
shopify.config.ts            # Configuración: store domain, version, private token
react-router.config.ts       # Configuración del framework (antes remix.config.ts)

La raíz del proyecto tiene un shopify.config.ts donde se fija la versión del Storefront API y las credenciales. La versión tiene que coincidir con la versión que usas en tus queries GraphQL — un mismatch produce errores en campos que no existen en esa versión.

Rutas y loaders

React Router v7 en modo framework opera con un modelo de datos simple: cada archivo de ruta puede exportar una función loader que corre en el servidor, y el componente default del archivo corre en el cliente (o en el servidor durante SSR). El hook useLoaderData conecta ambos.

~/proyectos/shopify/brew-atlas/brew-atlas-hydrogen/app/routes/products.$handle.tsx

import { type LoaderFunctionArgs } from 'react-router';
import { useLoaderData } from 'react-router';
import { Money, Image } from '@shopify/hydrogen';
 
export async function loader({ params, context }: LoaderFunctionArgs) {
  const { handle } = params;
  const { product } = await context.storefront.query(PRODUCT_QUERY, {
    variables: { handle, country: 'CO', language: 'ES' },
    cache: context.storefront.CacheShort(),
  });
  if (!product) throw new Response('Not found', { status: 404 });
  return { product };
}
 
export default function ProductPage() {
  const { product } = useLoaderData<typeof loader>();
  return (
    <article>
      <Image
        data={product.featuredImage}
        sizes="(min-width: 768px) 50vw, 100vw"
        fetchpriority="high"
      />
      <h1>{product.title}</h1>
      <Money data={product.priceRange.minVariantPrice} />
    </article>
  );
}
 
const PRODUCT_QUERY = /* GraphQL */ `
  query Product($handle: String!, $country: CountryCode!, $language: LanguageCode!)
  @inContext(country: $country, language: $language) {
    product(handle: $handle) {
      id
      title
      handle
      featuredImage { url altText width height }
      priceRange {
        minVariantPrice { amount currencyCode }
      }
    }
  }
`;

Tres cosas a notar en este loader:

context.storefront.query: el objeto context.storefront es el cliente del Storefront API que Hydrogen inyecta en cada request. No lo instancias manualmente — está disponible en loader, action, y en las llamadas al servidor desde clientLoader. Tiene métodos query y mutate.

cache: context.storefront.CacheShort(): la caché es por request, no global. CacheShort() configura una ventana de caché de ~10 segundos para datos que cambian frecuentemente. Para páginas de colección que no cambian tanto, usas CacheLong() (~900 segundos). Para datos que nunca deben cachearse (carrito, datos del cliente), usas CacheNone().

@inContext: la directiva de contexto en la query pasa el país y el idioma al Storefront API, que responde con precios y contenido localizados. Sin @inContext, los compradores fuera del mercado primario de la tienda ven precios y textos del mercado por defecto. Es el error más frecuente en storefronts headless — se olvida en el calor del desarrollo y produce bugs de precios difíciles de reproducir.

Sistema de caché

Hydrogen tiene cuatro modos de caché integrados en el cliente del Storefront API:

La caché de Hydrogen usa la Cache API del runtime web (disponible en Oxygen y en navegadores). No es Redis, no es Memcached — es la misma abstracción que un Service Worker usaría para cachear resources. Funciona per-request basado en la URL y las variables de la query.

Carrito y sesión

Hydrogen gestiona el estado del carrito en una sesión cookie-based en el servidor. El carrito se crea en el Storefront API mediante la mutación cartCreate, y el cartId se almacena en la sesión. Las operaciones de carrito (agregar, eliminar, actualizar) son mutations del Storefront API que reciben el cartId.

El checkout ocurre fuera de tu storefront: cuando el comprador va a pagar, tu app redirige a cart.checkoutUrl, que es la URL del checkout nativo de Shopify. El checkout en sí no es personalizable desde Hydrogen — para eso están las Checkout UI Extensions del lado de la app.

Storefront API proxy (obligatorio desde 2026.4)

En versiones de Hydrogen anteriores a 2026.4, era posible hacer queries al Storefront API directamente desde el navegador usando el Storefront API public token. A partir de 2026.4, Shopify cambió esto como breaking change: el Storefront API token del servidor no se expone al cliente. Todas las queries al Storefront API desde código del cliente tienen que pasar por una ruta server-side.

El patrón correcto: las queries que antes corrían en useEffect del cliente ahora van en loader o en clientLoader (que puede llamar a un endpoint de tu propio servidor). El cliente nunca llama a myshopify.com/api/storefront/graphql directamente — llama a tu propia ruta /api/storefront-proxy que a su vez llama al Storefront API con el token de servidor.

Si tienes código de Hydrogen ≤ 2026.3 con queries en useEffect, eso rompió en 2026.4. La solución es mover esas queries a loaders o a rutas de API server-side.

Deploy a Oxygen

Oxygen es el runtime edge de Shopify para storefronts Hydrogen. Está basado en Workerd (el runtime de V8 Isolates de Cloudflare), distribuido globalmente, con cold starts bajo los 50ms. Cada environment de Hydrogen en Oxygen tiene su propia URL.

Desde ~/proyectos/shopify/brew-atlas/brew-atlas-hydrogen/:

npx shopify hydrogen link
npx shopify hydrogen deploy

El deploy crea un environment de preview con una URL del tipo https://brew-atlas-hydrogen-preview.shopify.io. La promoción de preview a producción se hace desde el dashboard de Hydrogen en el Partner Dashboard — no hay un comando CLI para esto. El ambiente anterior de producción queda como snapshot para rollback instantáneo.

Limitaciones de Oxygen

Oxygen es un runtime Workerd, lo que implica restricciones que hay que entender antes de diseñar la arquitectura:

• Sin filesystem: no puedes leer archivos en tiempo de runtime. Los assets estáticos se sirven como CDN assets desde el build.
• Sin Node.js APIs: dispones de las Web Standard APIs (fetch, WebStreams, Cache API, Crypto). Si tu código usa fs, path, o módulos de Node.js que no están en la Web Platform, va a fallar en Oxygen.
• Sin WebSockets: Oxygen no soporta conexiones WebSocket. Para datos en tiempo real (stock, precios), usas SSE (Server-Sent Events) o un servicio externo, o simplemente aceptas que el storefront se revalida por polling.
• ~128MB de memoria por isolate: suficiente para la mayoría de storefronts, limitante si intentas pre-cargar el catálogo completo en memoria.

Si alguna de estas limitaciones es bloqueante para tu caso de uso, Hydrogen puede desplegarse en cualquier entorno que hable Web Request/Response — Cloudflare Workers, Vercel Edge, o un servidor Node.js estándar. Oxygen es el default, no el único.

Puentes mentales

Estado 2026

Lo relevante al 2026:

• Versión: 2026.4.0. Hydrogen sigue el mismo calendario de versiones trimestral que el Storefront API. El campo apiVersion en shopify.config.ts debe coincidir con la versión del Storefront API que usas en las queries.
• React Router v7: desde septiembre 2025, los imports son de react-router, no de @remix-run/react. El react-router.config.ts reemplaza al remix.config.ts.
• Proxy obligatorio: desde 2026.4, las queries al Storefront API desde el cliente tienen que pasar por una ruta server-side. El Storefront API public token no se expone al navegador.
• Codegen: el template de Hydrogen incluye generación de tipos TypeScript desde las queries GraphQL. Los tipos generados están en graphql/ y se actualizan con npx shopify hydrogen codegen.

Proyecto · Brew Atlas

cd ~/proyectos/shopify/brew-atlas
npm create @shopify/hydrogen@latest
# Nombre: brew-atlas-hydrogen
# Vincular store: si (usar dev store)
# Instalar dependencias: si

Errores comunes

// ~/proyectos/shopify/brew-atlas/brew-atlas-hydrogen/app/routes/products.$handle.tsx
// Loader con queries en paralelo
export async function loader({ params, context }: LoaderFunctionArgs) {
  const [{ product }, { collection }] = await Promise.all([
    context.storefront.query(PRODUCT_QUERY, {
      variables: { handle: params.handle! },
      cache: context.storefront.CacheShort(),
    }),
    context.storefront.query(RELATED_COLLECTION_QUERY, {
      variables: { handle: 'coffees' },
      cache: context.storefront.CacheLong(),
    }),
  ]);
  if (!product) throw new Response('Not found', { status: 404 });
  return { product, collection };
}

Checklist senior

Siguiente

Con Hydrogen cubriendo el stack headless, el bloque siguiente aborda los temas que separan al desarrollador competente del desarrollador senior en el ecosistema Shopify: Core Web Vitals actualizados para 2026, Markets, B2B, localización, accesibilidad, y observabilidad en producción.