Por qué Horizon no tiene main-cart-items.liquid (y cómo personalizar cart-items-component en su lugar)

Horizon no cuenta con un archivo de sección main-cart-items.liquid. Ese archivo existe en Dawn, no en Horizon. En Horizon, la renderización de artículos del carrito se maneja mediante main-cart.liquid (la sección) junto con el elemento web personalizado cart-items-component. Personalizar el carrito significa trabajar dentro de esa arquitectura de componentes web en lugar de editar una sección Liquid plana.

Puntos clave

• Horizon reemplazó el patrón monolítico main-cart-items.liquid con un componente web cart-items-component independiente.
• Editar archivos centrales de Horizon directamente será sobrescrito en la próxima actualización del tema (Horizon envía versiones semanales).
• Los atributos del carrito van en main-cart-footer.liquid; las propiedades de elementos de línea se renderizan mediante iteración cart.items dentro de main-cart.liquid.
• La ruta segura de personalización es: archivos de bloque nuevos en blocks/, archivos de sección con prefijo, y una rama upstream de GitHub para aplicar las actualizaciones de Shopify correctamente.
• Las aplicaciones creadas para la arquitectura anterior de Online Store 2.0 frecuentemente se rompen en el carrito de Horizon porque los componentes web se ejecutan dentro de Shadow DOM.

Por qué el archivo que buscas no existe

La documentación de ayuda de Shopify e innumerables tutoriales hacen referencia a main-cart-items.liquid porque así es como Dawn estructura su carrito. Dawn divide la página del carrito en dos secciones: main-cart-items.liquid (la tabla de elementos de línea) y main-cart-footer.liquid (totales, botón de pago, atributos). Horizon no replica esta división.

Horizon es el buque insignia de una nueva generación de temas de Shopify construido sobre el marco Horizon. El principio arquitectónico es: cada parte interactiva significativa de la página es un elemento web independiente y autocontendio. El cajón del carrito, el selector de variantes, la búsqueda predictiva, ninguno de ellos son secciones Liquid monolíticas como las implementa Dawn. En su lugar, son elementos personalizados encapsulados compuestos dentro de un único archivo de sección main-cart.liquid.

Esto causó confusión inmediata cuando Horizon se lanzó en Summer Editions 2025. Para febrero de 2026, los foros de la comunidad de Shopify estaban llenos de comerciantes en Horizon 3.3.0 buscando main-cart-items.liquid en su directorio sections/ sin encontrar nada, porque nunca estuvo allí.

Cómo se ve realmente la arquitectura del carrito de Horizon

En lugar de un archivo de sección separado por zona del carrito, la página del carrito de Horizon se estructura alrededor de main-cart.liquid como sección externa, con el elemento personalizado <cart-items-component> manejando la renderización interactiva de elementos de línea dentro de él.

Las decisiones arquitectónicas clave, directamente del repositorio oficial de Horizon en GitHub:

• Renderizado primero en el servidor. El HTML es renderizado por los servidores de Shopify mediante Liquid. La lógica comercial como formato de dinero y traducciones permanece en el servidor, no en el cliente.
• Mejora progresiva nativa web. El tema se orienta a navegadores modernos sin polyfills, y la renderización asincrónica del estado del carrito (actualizaciones de cantidad, eliminaciones) se maneja con parsimonia como mejora progresiva sobre el HTML renderizado por el servidor.
• JavaScript con alcance. Horizon incluye una clase JS específica que mide el rendimiento de componentes como el formulario de producto, el cajón del carrito y el descuento del carrito, manteniendo el peso de JS mínimo por componente.

El cart-items-component es el elemento personalizado (<cart-items-component>) que envuelve la tabla de elementos de línea. Escucha eventos de cambio del carrito (agregar, eliminar, actualizar cantidad) y re-renderiza su HTML interno mediante la Cart Ajax API sin recargar la página completa. Su plantilla Liquid vive dentro de main-cart.liquid, no en un archivo separado.

Atributos del carrito (campos personalizados a nivel de pedido como un mensaje de regalo o un selector de fecha) se capturan mediante main-cart-footer.liquid. Según la documentación de plantilla de carrito de Shopify, agregas un <input> con name="attributes[tu-nombre-de-campo]" y form="cart" dentro de ese archivo de pie de página. Ese atributo es entonces accesible mediante {{ cart.attributes['tu-nombre-de-campo'] }}.

Propiedades de elementos de línea (datos personalizados por producto) no son renderizadas automáticamente por cart-items-component. Necesitas hacer un bucle en cart.items dentro de main-cart.liquid y mostrar el hash .properties de cada artículo. La propia documentación de Shopify señala que si se agrega dos veces el mismo artículo con propiedades de elemento de línea únicas, se dividen en elementos de línea separados, un comportamiento que vale la pena considerar en tu lógica de plantilla.

Cómo personalizar el carrito de forma segura en Horizon

Horizon lanza actualizaciones de tema semanales. Si editas archivos centrales directamente, esas ediciones serán sobrescritas la próxima vez que apliques una actualización. El repositorio de GitHub incluso señaló una discrepancia de versión activa: a partir de abril de 2026, la Tienda de Temas estaba en v3.5.1 mientras que el repositorio de GitHub estaba fijado en v3.4.0, lo que significa que algunos cambios llegaban primero a la tienda. Esto refuerza la necesidad de un flujo de trabajo Git adecuado.

La configuración de rama de GitHub de tres ramas

La guía oficial de Growth Services de Shopify (publicada en noviembre de 2025) recomienda gestionar todas las personalizaciones de Horizon mediante una estrategia de ramificación disciplinada:

1. upstream/horizon, rastrea el repositorio oficial Shopify/horizon directamente. Aquí extraes las actualizaciones primero.
2. main, tu rama personalizada lista para producción. Fusionas upstream en main después de revisar los cambios.
3. Ramas de características, todas las nuevas personalizaciones del carrito se construyen aquí y se envían como PR a main.

Para conectar upstream, navega a tu carpeta de tema local y ejecuta:

git remote add upstream https://github.com/Shopify/horizon.git
git fetch upstream

Cuando Shopify envía una nueva versión de Horizon, extrae en tu rama upstream, resuelve conflictos en tus archivos personalizados y fusiona. Esto mantiene tus personalizaciones del carrito intactas en cada actualización semanal.

Dónde colocar realmente tus personalizaciones del carrito

Evita la tentación de copiar el main-cart.liquid completo en una versión con prefijo custom. a menos que sea absolutamente necesario. Una copia completa significa que tienes que hacer diff manual y re-aplicar manualmente cada actualización futura de Shopify a esa sección. En su lugar, agrega solo lo que necesites en archivos de bloque nuevos cuando sea posible, y mantén la sección central intacta.

Construir extensiones de carrito interactivas como componentes web

La filosofía de rendimiento de Horizon es explícita: sin bibliotecas externas de carrusel o interfaz. Si necesitas comportamiento interactivo dentro del carrito (un incrementador de cantidad animado, una barra de progreso de envío gratis en tiempo real), constrúyelo como un componente web Vanilla que se inicialice solo cuando sea visible. Usa IntersectionObserver para diferir la inicialización en cualquier cosa que no esté inmediatamente en el viewport, y escribe tus estilos dentro de etiquetas {% style %} para mantenerlos con alcance y libre de solicitudes HTTP adicionales.

class CartUpsellBadge extends HTMLElement {
  connectedCallback() {
    // Inicializar solo cuando el carrito esté abierto o elemento sea visible
    this._observer = new IntersectionObserver((entries) => {
      if (entries[0].isIntersecting) {
        this._init();
        this._observer.disconnect();
      }
    });
    this._observer.observe(this);
  }

  _init() {
    // Obtener datos de venta adicional, renderizar en this.innerHTML
  }
}
customElements.define('cart-upsell-badge', CartUpsellBadge);

Carga este script mediante <script type="module"> para que el navegador lo maneje eficientemente, coincidiendo con el patrón de carga de script propio de Horizon.

El problema de compatibilidad de aplicaciones de Shadow DOM

Este es el detalle que atrapa a la mayoría de comerciantes en medio del proyecto. Las aplicaciones construidas para la arquitectura anterior de Online Store 2.0 de Dawn frecuentemente se enganchan en el carrito consultando el DOM por una entrada de cantidad o un intervalo de total del carrito y escuchando eventos de cambio. Ese patrón se rompe en Horizon.

Porque los componentes del carrito de Horizon son componentes web, las aplicaciones que usan encapsulación Shadow DOM bloquean el patrón antiguo document.querySelector('.cart-item__quantity'). Los internos del elemento personalizado no son accesibles desde fuera de la raíz de sombra mediante consultas DOM estándar.

Antes de instalar cualquier aplicación de carrito en Horizon, verifica explícitamente la descripción de la aplicación para una nota de "soporte Horizon". Las aplicaciones que recibieron una insignia "Built for Shopify" han sido probadas en rendimiento, pero el estado de la insignia por sí solo no garantiza compatibilidad con Shadow DOM. En caso de duda, instala en un tema duplicado y prueba actualizaciones de cantidad, eliminaciones y el flujo de pago de extremo a extremo antes de ir en vivo.

El retraso actual de GitHub y lo que significa para ti

A mediados de 2026, el repositorio Shopify/horizon en GitHub ha tenido períodos en los que se retrasa con respecto a la versión activa en la Tienda de Temas. En abril de 2026, desarrolladores de la comunidad notaron que el repositorio estaba en v3.4.0 mientras que la Tienda de Temas servía v3.5.1. Shopify confirmó que la rama principal puede incluir código para características no lanzadas aún, lo que significa que el tema publicado y el repositorio pueden estar desincronizados en ambas direcciones.

Implicación práctica: no trates el repositorio de GitHub como la fuente canónica de la versión en ejecución en tu tienda. Extrae el tema más reciente de tu administración de Shopify (Online Store > Temas > Descargar archivo de tema) y comparalo con el repositorio de GitHub antes de hacer suposiciones sobre qué código está activo. Usa Theme Check (incluido en Shopify CLI y disponible como extensión de VS Code que Horizon recomienda automáticamente) para validar tu Liquid antes de cada despliegue.

Una nota sobre el error del navegador en la aplicación de Instagram (junio de 2026)

Un problema activo que vale la pena saber: a partir de la semana del 14 de junio de 2026, varios comerciantes de Horizon reportaron que la navegación adicional después de la carga inicial de la página dentro de los navegadores en aplicación de Instagram, Facebook y TikTok produce una pantalla en blanco. El equipo de temas de Shopify reconoció el problema el 17 de junio de 2026, confirmó que existe una solución, y dijo que la causa raíz puede estar relacionada con el comportamiento del navegador en aplicación en lugar del tema mismo. Si estás ejecutando campañas de comercio social que generan tráfico a través de estos navegadores en aplicación, contacta con Shopify Support para obtener la solución actual mientras se completa la corrección completa.

Resumen: el modelo mental correcto para el carrito de Horizon

Deja de buscar main-cart-items.liquid. Es un concepto de Dawn. El carrito de Horizon es:

• Una sección externa: main-cart.liquid
• Un componente web interactivo: <cart-items-component> manejando re-renderizados Ajax
• Una sección de pie de página: main-cart-footer.liquid para atributos del carrito y el formulario de pago
• Directorio de bloques: donde viven todas tus adiciones personalizadas

Trabaja dentro de ese modelo, gestiona tus cambios mediante una rama upstream de GitHub adecuada, y puedes personalizar el carrito de Horizon de forma segura sin preocuparte por cada actualización semanal.

Si necesitas ayuda práctica para construir una experiencia de carrito personalizada en Horizon, consulta lo que hacemos como desarrollador de temas de Shopify o revisa nuestro servicio de optimización de velocidad de Shopify si el rendimiento del carrito es la preocupación subyacente.