16 · Performance y temas senior

Qué es y por qué existe

El perfil del desarrollador Shopify senior no se define por conocer la documentación de cada API — eso lo hace cualquiera con tiempo suficiente. Se define por la capacidad de tomar decisiones correctas en intersecciones difíciles: cuándo un theme alcanza su límite y un storefront headless tiene sentido, cómo diseñar para mercados internacionales desde el principio en lugar de retrofit, cómo medir performance de forma que los números reflejen la experiencia real del comprador, y cómo mantener un sistema en producción con suficiente observabilidad para diagnosticar problemas antes de que los reporte un cliente.

Esta sección cubre esos temas transversales. No son features — son capacidades que aplicas en cualquier capa del stack que hayas construido en las secciones anteriores.

Core Web Vitals 2026

Google mide la experiencia de usuario de páginas web con tres métricas que también usa como señal de ranking en búsqueda. Para 2026, los umbrales del percentil 75 son:

INP (Interaction to Next Paint) reemplazó a FID (First Input Delay) en marzo de 2024. La diferencia es sustancial: FID solo medía la latencia del primer input. INP mide TODAS las interacciones durante la vida de la página y reporta el peor percentil. Un filtro de búsqueda de catálogo que tarda 300ms en actualizar el DOM es invisible en FID pero impacta directamente en INP.

LCP: el peso de la imagen héroe

El LCP en un storefront de e-commerce casi siempre es la imagen principal del producto o del hero de la página de inicio. Las optimizaciones que más impactan:

En themes Liquid:

{%- comment -%}
  El filtro image_url genera la URL con el tamaño correcto.
  width/height evitan CLS. fetchpriority="high" marca la imagen como LCP.
  loading="eager" desactiva lazy-load para la imagen que va above the fold.
{%- endcomment -%}
<img
  src="{{ section.settings.hero_image | image_url: width: 1200 }}"
  width="{{ section.settings.hero_image.width }}"
  height="{{ section.settings.hero_image.height }}"
  alt="{{ section.settings.hero_image.alt | escape }}"
  loading="eager"
  fetchpriority="high"
>

El error más frecuente es loading="lazy" en la imagen héroe — es el default que muchos temas aplican globalmente para reducir el uso de red, pero en la imagen above the fold hace exactamente lo contrario: retrasa el LCP. Solo las imágenes below the fold deben tener loading="lazy".

En Hydrogen:

~/proyectos/shopify/brew-atlas/brew-atlas-hydrogen/app/routes/_index.tsx

import { Image } from '@shopify/hydrogen';
 
// El componente Image de Hydrogen genera los srcset correctos para la CDN.
// sizes le indica al navegador qué tamaño esperar en cada breakpoint.
<Image
  data={hero.image}
  sizes="100vw"
  loading="eager"
  fetchpriority="high"
  className="w-full aspect-[16/9] object-cover"
/>

INP: evitar trabajo en el hilo principal

INP mide la latencia entre una interacción del usuario (clic, teclado, tap) y el siguiente repintado de pantalla. Los culpables frecuentes en storefronts Shopify:

• JavaScript de terceros sincrónico: chat widgets, analytics, pixel de publicidad que bloquean el hilo principal. La solución es cargarlos con async o defer, o moverlos a un Web Worker cuando sea posible.
• Event handlers costosos: un handler de change en un selector de talla que recalcula el precio, actualiza el carrito preview, y actualiza el stock — todo en el mismo tick. La solución es debounce/throttle y separar las operaciones de actualización de UI inmediata (síncronas) de las que requieren red (asíncronas).
• Hydration masiva: en Hydrogen, el useLoaderData data flota al cliente como JSON en el HTML. Si ese JSON es muy grande, la hydration que ejecuta React al cargar el bundle puede bloquear el hilo por varios frames. La solución es defer() con <Await> para mover datos no críticos fuera del render inicial.

CLS: dar tamaño a todo lo que no se conoce

CLS ocurre cuando elementos sin tamaño reservado aparecen o cambian durante la carga, empujando el contenido visible. Las causas frecuentes:

• Imágenes sin width/height: el navegador no puede reservar espacio antes de descargarla. Siempre declarar ambos atributos — en Liquid con el filtro image_url: width: X y las propiedades .width/.height del objeto imagen; en Hydrogen con el componente <Image data={...}> que los incluye desde el Storefront API.
• Fuentes web sin font-display: optional o swap: el layout shift de texto al cargar la fuente. Usar font-display: swap y precargar las fuentes críticas con <link rel="preload" as="font">.
• Banners de consentimiento de cookies: aparecen de repente y empujan el contenido. Reservar espacio fijo o usar un overlay que no mueve el layout.

Lighthouse CI en themes

La manera de no encontrarse sorpresas en producción es medir en cada deploy. El flujo recomendado para themes de Shopify:

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

shopify theme push --environment preview

Después del push, desde cualquier directorio:

npx lighthouse https://brew-atlas.myshopify.com?preview_theme_id=XXXX \
  --output json \
  --output-path ./lighthouse-results.json \
  --chrome-flags="--headless"
 
npx budget-check ./lighthouse-results.json \
  --lcp 2500 \
  --inp 200 \
  --cls 0.1

shopify theme check valida problemas de código Liquid (variables sin definir, accesos a recursos inexistentes, problemas de performance conocidos). No reemplaza a Lighthouse — los dos se complementan.

Markets

Markets es la feature de Shopify para comercio internacional en una sola tienda. En lugar de gestionar múltiples tiendas por país, configuras markets desde Admin → Markets, y cada market tiene su propia configuración de:

• Moneda: conversión automática a tipo de cambio live, o precios fijados manualmente por market
• Idioma: uno o más idiomas por market
• Dominio o subpath: shop.es, shop.com/fr, o shop.com.ar
• Precios diferenciados: puedes tener un precio diferente en AR que en CO para el mismo producto
• Impuestos y aranceles: configuración de si los precios incluyen IVA, gestión de derechos de importación

Markets en el Storefront API

El parámetro @inContext de la sección anterior no es solo una sugerencia de localización — es el mecanismo para que el Storefront API te devuelva precios y contenido del market correcto para el comprador:

# La directiva @inContext recibe country (moneda) y language (traducción).
# Si omites @inContext, el Storefront API responde con el market primario de la tienda.
query ProductPrice($handle: String!)
@inContext(country: CO, language: ES) {
  product(handle: $handle) {
    priceRange {
      minVariantPrice { amount currencyCode }
    }
  }
}

En Hydrogen, el country y language del comprador vienen del objeto buyerIdentity de la sesión. Si el comprador está navegando desde Argentina, quieres pasar country: AR para que los precios estén en ARS. La forma más robusta de determinarlo es desde el header CF-IPCountry (Cloudflare) o desde un cookie de preferencia de mercado explícita del comprador.

Geo-redirect

Shopify gestiona el geo-redirect automático basado en la configuración de markets — no necesitas construir tu propio sistema de detección de país. Si el comerciante tiene el market de Argentina con dominio shop.com.ar, Shopify detecta la IP argentina y redirige. En Hydrogen, el redirect lo manejas en el loader de la ruta raíz consultando el header de país.

No construyas tu propio sistema de geo-redirect si puedes usar el de Shopify o el del CDN que lo soporte. Los sistemas de geo-redirect caseros tienen dos problemas: VPNs y edge cases de routing en redes móviles internacionales.

B2B en Shopify

Desde 2023, las funcionalidades B2B de Shopify son nativas — no requieren apps de terceros para las funcionalidades centrales. El modelo de datos B2B se estructura en:

• Company: la empresa compradora. Tiene nombre, tax ID, y metadatos del negocio.
• CompanyLocation: cada ubicación física o punto de entrega de la empresa (una empresa puede tener 50 sucursales).
• CompanyContact: los individuos de la empresa que pueden comprar — pueden tener roles distintos (admin de la empresa, simple comprador).
• Net payment terms: la empresa puede tener términos Net 15, Net 30, o Net 60. El checkout de B2B soporta pago diferido — el pedido se crea, se entrega, y se paga después según los términos acordados.

B2B en el Storefront API

Cuando un comprador B2B autenticado hace una query al Storefront API, puedes incluir el contexto B2B en @inContext para obtener los precios y los términos de pago específicos de su empresa:

query PriceList($handle: String!)
@inContext(
  country: CO,
  language: ES,
  buyerIdentity: {
    companyLocationId: "gid://shopify/CompanyLocation/123"
  }
) {
  product(handle: $handle) {
    priceRange {
      minVariantPrice { amount currencyCode }
    }
    # El precio devuelto ya es el precio B2B de esa CompanyLocation
  }
}

En el Admin API, los recursos B2B están en los tipos company, companyContact, y companyLocation. Las draftOrder del Admin API soportan contexto B2B con precios de catálogo B2B y términos de pago diferido.

UX para B2B

El comprador B2B ve la tienda diferente al comprador retail:

• Los precios son los de su catálogo de empresa — menores que el precio público, generalmente.
• En el checkout, en lugar de pagar con tarjeta de crédito, puede seleccionar “Net 30” si su empresa tiene ese término configurado.
• El historial de pedidos muestra pedidos de la empresa, no solo los suyos individuales (si tiene el rol de admin de empresa).

En un theme, verificas si el comprador es un contacto B2B con customer.b2b? en Liquid antes de renderizar elementos específicos de B2B (precios de volumen, selector de ubicación de empresa, etc.).

Localización

La localización en Shopify tiene tres dimensiones que hay que tratar por separado:

Traducciones de contenido: el contenido del catálogo (títulos de productos, descripciones, metafields) se traduce con Shopify Translate & Adapt (la herramienta oficial, incluida en todos los planes) o con apps de terceros. Las traducciones se almacenan como metafields en el namespace de traducción del recurso. En el Storefront API, solicitar el idioma en @inContext(language: FR) hace que Shopify devuelva el contenido traducido automáticamente si existe la traducción.

Traducciones de UI del theme: las cadenas de texto hardcodeadas en el theme (como “Agregar al carrito”, “Continuar comprando”, etc.) se gestionan en los archivos locales/*.json del theme. El tag Liquid {{ 'add_to_cart' | t }} busca la cadena en el archivo de locale activo.

Formato de moneda y números: el filtro | money en Liquid formatea el precio según el locale activo de la tienda. En Hydrogen, el componente <Money> hace lo mismo. Para fechas y números generales, usá la API Intl.DateTimeFormat y Intl.NumberFormat de JavaScript, pasando el locale del comprador.

RTL (right-to-left): árabe, hebreo, y persa se escriben de derecha a izquierda. Shopify no aplica RTL automáticamente — cuando el locale es RTL, tienes que agregar dir="rtl" al elemento <html> y asegurarte de que el CSS del theme use propiedades lógicas (margin-inline-start en lugar de margin-left) o incluya overrides RTL específicos.

Accesibilidad (WCAG 2.2 AA)

El estándar mínimo para un theme publicado en el Theme Store y para una app en el App Store es WCAG 2.2 nivel AA. Los criterios que más fácilmente se violan en contextos de e-commerce:

Contraste de color: el texto sobre fondo debe tener una relación de contraste de ≥ 4.5:1 para texto normal y ≥ 3:1 para texto grande (18px bold o 24px regular). Los botones de CTA con colores de marca frecuentemente fallan este criterio cuando el diseñador prioriza la estética sobre el contraste.

Focus visible: los elementos interactivos deben tener un outline visible cuando reciben foco del teclado. El CSS outline: none en :focus viola WCAG. La solución correcta es reemplazar el outline por un estilo de focus propio que sea igual o más visible, no eliminarlo.

Labels en formularios: cada <input> debe tener un <label> asociado (con for/id matching) o un atributo aria-label. Formularios de checkout y de login en themes con diseños minimalistas frecuentemente usan placeholders en lugar de labels — eso no cumple el criterio.

Navegación por teclado completa: menús, modales, y dropdowns deben ser navegables con Tab y cerrables con Escape. Los menús de navegación en themes que solo funcionan con hover del mouse fallan este criterio.

ARIA con moderación: ARIA (Accessible Rich Internet Applications) solo debe usarse cuando HTML nativo no puede expresar la semántica necesaria. Un botón es un <button>, no un <div role="button">. Un campo de texto es un <input type="text">, no un <div contenteditable>. El uso excesivo de ARIA para parchear HTML semánticamente incorrecto produce peor experiencia que el HTML correcto sin ARIA.

Observabilidad

Un storefront en producción sin observabilidad es un sistema que solo puedes diagnosticar cuando un cliente se queja. La observabilidad en el ecosistema Shopify tiene tres capas:

Logs de runtime (Hydrogen/Oxygen): Oxygen permite configurar un log drain que envía los logs del servidor a un agregador externo (Datadog, Logtail, Axiom). Los errores de loader, los timeouts de Storefront API, y los crashes de renderizado quedan registrados. Sin log drain, los errores de Oxygen son visibles solo en el dashboard de Partner — acceso reactivo, no proactivo.

Eventos de analytics (Themes y Hydrogen): Shopify Web Pixels es el sistema de analytics de Shopify. Los Web Pixels reciben eventos del storefront (page view, add to cart, purchase) y los envían a los destinos configurados (Google Analytics, Meta Pixel, etc.). El Consent API de Shopify gestiona el consentimiento de cookies — tus pixels deben respetar la preferencia del comprador antes de enviar datos.

Webhooks: los webhooks de Shopify deben responder dentro de los 5 segundos o Shopify los marca como fallidos y reintenta. El trabajo pesado (sincronización a una base de datos, envío de emails, llamadas a APIs externas) no puede correr en el handler del webhook. El patrón correcto es: el handler recibe el webhook, lo encola en una cola de mensajes (BullMQ, AWS SQS, Google Pub/Sub), responde 200, y un worker procesa la tarea en background.

Alertas de rate limiting: el Admin API devuelve el estado del bucket en extensions.cost.throttleStatus. En apps que hacen muchas queries al Admin API, monitorear currentlyAvailable y alertar cuando baja de 200 puntos (20% del bucket de 1000) previene errores THROTTLED en producción.

Gestión de costo del Admin API

Para operaciones que procesan datasets grandes (importar precios, actualizar metafields en masa, sincronizar inventario desde un ERP), hay dos niveles de estrategia:

Para datasets medianos (hasta ~5000 registros): paginación manual con first: 50 y respeto al costo del bucket. La clave es monitorear extensions.cost.throttleStatus.currentlyAvailable en cada respuesta y pausar con backoff cuando el bucket está bajo.

Para datasets grandes (>50.000 registros): bulk operations. La mutation bulkOperationRunQuery procesa datasets de millones de registros en background de Shopify. Para mutaciones masivas (actualizar metafields en 100.000 productos), bulkOperationRunMutation recibe un archivo JSONL de entradas. Solo puede haber una bulk operation activa por tienda.

Para fanout de eventos (webhooks con muchos subscribers): en lugar de múltiples subscripciones de webhooks a distintos servicios, usá los Webhook Topics de Shopify que integran con AWS EventBridge o Google Cloud Pub/Sub. Un solo topic de Shopify puede tener cientos de subscribers en EventBridge sin que Shopify sepa ni importe.

Debugging senior

Las herramientas que un desarrollador senior usa para diagnosticar problemas en producción en Shopify:

• Partner Dashboard → Events: timeline de todos los webhooks, errores de API, y eventos de app de las últimas 72 horas. El primer lugar para ir cuando un comerciante reporta que “algo está raro”.
• GraphiQL embebido: el template de apps de Shopify incluye un endpoint /graphiql con el Admin API GraphQL explorer autenticado. Permite probar queries del Admin API contra la tienda real sin postman ni código.
• shopify theme check: valida el código Liquid del theme contra las mejores prácticas y detecta errores de sintaxis, accesos a variables no definidas, y patrones de performance problemáticos.
• Hydrogen DevTools: la extensión de React DevTools en el browser muestra el árbol de componentes y los datos de useLoaderData. Para depurar por qué un componente recibe datos inesperados, es más rápido que los logs.
• Shopify Flow: para automatización operacional — cuando X ocurre en la tienda, ejecutar Y. Útil para detectar patrones operacionales problemáticos (órdenes con combinaciones de variantes imposibles, clientes con datos duplicados) que no son errores de código pero afectan la operación.

Puentes mentales

Estado 2026

Lo relevante al 2026:

• INP reemplazó a FID en 2024: si lees artículos de performance anteriores a 2024 que mencionan FID como la tercera Core Web Vital, ya no es así. INP es la métrica vigente. Las optimizaciones para FID y para INP tienen cierta superposición, pero INP es más amplio y más estricto.
• Markets disponible en todos los planes: desde 2023, Markets ya no está limitado a Shopify Plus. Cualquier tienda puede configurar markets internacionales.
• B2B nativo desde 2023: las funciones B2B centrales (companies, locations, contacts, net payment terms) son nativas en Shopify Plus. Para planes inferiores, sigue requiriendo apps de terceros como Handshake o Ordermentum.
• WCAG 2.2 (septiembre 2023): la versión vigente es 2.2, que agrega nueve criterios nuevos respecto a 2.1. Los más relevantes para e-commerce son el “Focus Not Obscured” (los elementos con foco no deben quedar ocultos por headers sticky) y el “Target Size Minimum” (los elementos clickeables deben tener al menos 24x24px).

Proyecto · Brew Atlas

npx lighthouse https://brew-atlas.myshopify.com \
  --preset desktop \
  --output json \
  --output-path ~/proyectos/shopify/brew-atlas/audits/lighthouse-result.json

Errores comunes

// ~/proyectos/shopify/brew-atlas/brew-atlas-hydrogen/app/routes/products.$handle.tsx
// Loader con datos diferidos
export async function loader({ params, context }: LoaderFunctionArgs) {
  // No hacer await — el loader retorna inmediatamente
  const relatedProducts = context.storefront.query(RELATED_QUERY, {
    variables: { handle: params.handle! },
    cache: context.storefront.CacheLong(),
  });
 
  const { product } = await context.storefront.query(PRODUCT_QUERY, {
    variables: { handle: params.handle! },
    cache: context.storefront.CacheShort(),
  });
 
  return defer({ product, relatedProducts });
}

Checklist senior

Siguiente

El bloque final cubre el cierre del ciclo: cómo llevas un proyecto Shopify de producción al App Store o al Theme Store, qué significa Built for Shopify, el checklist completo de un desarrollador senior, y el go-live plan de Brew Atlas.