Cómo actualizar un tema de Shopify sin perder personalizaciones ni componentes custom

Actualizar un tema Shopify personalizado requiere revisar qué conserva la actualización y qué necesita migración manual. Shopify copia los ajustes del editor y puede trasladar cambios de código que no entren en conflicto con la nueva versión. Si no puede incluir esos cambios, debes adaptarlos y trasladarlos a un tema sin publicar. Instalar una copia limpia del proveedor también requiere migrar las personalizaciones.

Esta guía presenta un flujo de migración manual con ejemplos de Git, Liquid y Shopify CLI. Sigue las etapas del trabajo que hice para Charlotte’s Web: inventario de secciones, migración de settings y código custom, adaptación de estilos y pruebas del flujo completo en staging. Los ejemplos son didácticos; no reproducen el código del cliente. Mi entrega en ese proyecto llegó a staging; el paso de publicación de esta guía es una recomendación general.

Qué conserva una actualización de tema Shopify

En un tema viven dos tipos de personalización, y se comportan distinto:

Dónde vive	Ejemplos	Qué le hace la actualización
Archivos de código (secciones, componentes custom, snippets)	sections/*.liquid, snippets/*.liquid, assets/*.css, assets/*.js, layout/theme.liquid	Shopify puede incluir cambios sin conflictos; los que no pueda trasladar requieren migración manual.
Datos de configuración y diseño	config/settings_data.json, templates/*.json, grupos de secciones	Shopify copia las personalizaciones del editor. En una migración manual, hay que comprobar su compatibilidad con los ids y esquemas nuevos.

Cuando se requiere migración manual, separa el trabajo en reconciliar el código y adaptar la configuración. La copia actualizada debe revisarse antes de publicar, incluso si Shopify informa que incluyó los cambios de código.

Si quieres primero la versión de Shopify, el Centro de ayuda explica cómo las actualizaciones de tema interactúan con los cambios de código.

Paso 0: nunca trabajes sobre el tema publicado

Descarga el tema publicado en un repositorio git para que cada cambio sea visible y reversible. Con Shopify CLI:

mkdir store-theme && cd store-theme
shopify theme pull --store my-store --live
git init && git add -A && git commit -m "Tema publicado con personalizaciones"

--live (-l) descarga el tema publicado y --store acepta el prefijo de la tienda o la URL completa myshopify.com. A partir de aquí trabajas sobre copias y el tema publicado queda intacto.

Paso 1: encuentra qué se personalizó

Necesitas dos copias vanilla limpias del proveedor: la misma versión que sirve de base al tema actualmente publicado (v1) y la nueva (v2). v1 no necesariamente es la primera versión que tuvo la tienda. Si no puedes conseguir esa base exacta, el diff mezcla cambios del proveedor y personalizaciones; no lo uses como una migración automática fiable. Mantén las copias junto al tema publicado:

theme-upgrade/
├── vendor/
│   ├── v1/      # versión vanilla correspondiente al tema publicado
│   └── v2/      # nueva versión vanilla
└── live/        # el tema personalizado que acabas de descargar

La diferencia entre v1 y live es tu inventario de personalizaciones. Git puede comparar carpetas normales:

git diff --no-index --stat vendor/v1 live
git diff --no-index --name-status vendor/v1 live
git diff --no-index --name-status vendor/v1 vendor/v2

La diferencia entre v1 y live identifica archivos agregados, modificados y eliminados por personalizaciones, apps o configuración del comerciante. Compara además v1 con v2 para identificar los cambios del proveedor. git diff --no-index devuelve 1 cuando encuentra diferencias; ese resultado no significa que la comparación falló.

Paso 2: merge de tres vías, no copiar y pegar

Un merge de tres vías usa v1 como base para combinar cambios propios y del proveedor. No garantiza que el resultado sea funcional: los conflictos y los cambios de arquitectura requieren revisión manual. Git documenta los argumentos y códigos de salida de git merge-file.

git merge-file hace justo eso. Sus argumentos son tu archivo, la base y el archivo entrante:

git merge-file <actual> <base> <entrante>
# <actual>    = tu archivo personalizado (se sobrescribe con el resultado)
# <base>      = versión vendor/v1
# <entrante>  = versión vendor/v2

Este ejemplo prepara una copia nueva y fusiona solo un archivo Liquid revisado, presente en las tres versiones. Cambia file por el archivo de tu inventario. El directorio upgrade debe estar libre; si ya existe, el script se detiene para evitar sobrescribirlo o crear carpetas anidadas.

#!/usr/bin/env bash
set -eu
file='sections/main-product.liquid'

if [ -e upgrade ] || [ -L upgrade ]; then
  echo "upgrade ya existe; usa un directorio nuevo." >&2
  exit 1
fi
for dir in live vendor/v1 vendor/v2; do
  if [ ! -f "$dir/$file" ]; then
    echo "Falta una de las tres versiones del archivo. $dir/$file" >&2
    exit 1
  fi
done

cp -R vendor/v2 upgrade
cp "live/$file" "upgrade/$file"
if git merge-file "upgrade/$file" "vendor/v1/$file" "vendor/v2/$file"; then
  echo "Fusionado; revisa el resultado. $file"
else
  status=$?
  if [ "$status" -le 127 ]; then
    echo "Conflictos: resuelve los marcadores antes de continuar." >&2
  else
    echo "Error de git merge-file; revisa los archivos y el mensaje de Git." >&2
  fi
  exit "$status"
fi

git merge-file devuelve 0 si la fusión no tiene conflictos, entre 1 y 127 si los hay, y un código de error distinto ante otros fallos. El script termina con un código no exitoso en ambos casos. Los marcadores <<<<<<<, ======= y >>>>>>> requieren resolución manual; una fusión sin marcadores también necesita pruebas.

Este ejemplo no migra todo el tema. Completa el inventario antes de subir el resultado:

• Reconciliar config/settings_data.json, templates/*.json, grupos de secciones y demás JSON por separado, conservando los datos del comerciante y comprobando tipos de sección, ids de ajustes y orden de bloques contra el tema nuevo.
• Copiar archivos custom agregados únicamente después de comprobar que el proveedor no añadió un archivo con la misma ruta.
• Revisar los archivos eliminados en live: la copia de v2 puede reintroducirlos. Decide si conservarlos, quitarlos o adaptar sus referencias antes de publicar.
• Revisar archivos eliminados o renombrados por el proveedor y sus dependencias. Una personalización puede requerir trasladarse a otra sección.
• Resolver assets binarios, como imágenes y fuentes, por selección o reemplazo; no pasarlos por git merge-file.

Paso 3: aísla lo que pertenece al tema

Lo que pidió ajuste en la actualización de Charlotte’s Web fue adaptar los estilos porque la nueva versión cambió la forma de leer las variables globales de estilo. El código personalizado que dependía de esas variables tuvo que ajustarse, y ese es el tipo de cambio que una actualización puede traer sin avisar.

No puedes evitar que un proveedor renombre cosas, pero sí puedes limitar el daño. Concentra toda dependencia de ajustes del tema en un solo snippet y haz que tu código personalizado dependa de tus propias variables:

{%- comment -%}
  snippets/brand-vars.liquid
  El único archivo que conoce los ids de ajustes del tema.
  Después de una actualización, este es el archivo a corregir.
{%- endcomment -%}
<style>
  :root {
    --brand-accent: {{ settings.color_accent | default: '#0a7a5c' }};
    --brand-radius: {{ settings.button_radius | default: 8 }}px;
  }
</style>

color_accent y button_radius son marcadores: los ids de ajustes cambian de tema en tema, así que búscalos en config/settings_schema.json del tema. Renderiza el snippet una vez en layout/theme.liquid:

{% render 'brand-vars' %}

Una sección personalizada puede usar var(--brand-accent) sin saber nada de los ajustes del tema. Su propio esquema se mantiene pequeño y explícito:

<section class="promo-strip">
  <h2>{{ section.settings.heading | escape }}</h2>
</section>

{% schema %}
{
  "name": "Franja promocional",
  "settings": [
    {
      "type": "text",
      "id": "heading",
      "label": "Título",
      "default": "Envío gratis esta semana"
    }
  ],
  "presets": [{ "name": "Franja promocional" }]
}
{% endschema %}

Paso 4: Tailwind sin pelear con el tema

Si tus personalizaciones usan Tailwind, evita que choque con el CSS del tema. Tailwind v4 admite un prefijo de clases, y la guía de actualización muestra las utilidades con prefijo escritas como variantes, por ejemplo tw:flex.

Para omitir Preflight (el reset base de Tailwind), importa solo las capas de tema y utilidades. La documentación de Preflight coloca el prefijo en ambos imports. Este ejemplo también compila con Tailwind 4.1.18:

/* tailwind.css */
@layer theme, base, components, utilities;
@import "tailwindcss/theme.css" layer(theme) prefix(tw);
@import "tailwindcss/utilities.css" layer(utilities) prefix(tw);

@source "./sections";
@source "./snippets";
@source "./layout";

Compílalo hacia assets/, desde donde Shopify lo sirve:

npm install tailwindcss @tailwindcss/cli
npx @tailwindcss/cli -i ./tailwind.css -o ./assets/custom-tailwind.css --minify

Cárgalo como cualquier otro asset del tema y usa las clases con prefijo en Liquid:

{{ 'custom-tailwind.css' | asset_url | stylesheet_tag }}

<div class="tw:flex tw:items-center tw:gap-4">
  {{ section.settings.heading | escape }}
</div>

El prefijo reduce las colisiones de nombres de clases y variables. No aísla por completo tu CSS: los selectores globales del tema, la cascada y los cambios en el marcado aún pueden afectar tus componentes. Revísalos en la vista previa.

Paso 5: prueba en un tema sin publicar

Sube el resultado fusionado como un tema nuevo sin publicar, nunca encima del publicado:

cd upgrade
shopify theme check
shopify theme push --store my-store --unpublished --theme "Upgrade 2026-10"

shopify theme check revisa el Liquid, y --unpublished crea un tema nuevo y, sin --development, toma su nombre de --theme. Para iterar con recarga en caliente contra ese tema:

shopify theme dev --store my-store --theme "Upgrade 2026-10"

Después recorre todo el flujo del usuario en la vista previa, no solo las páginas que editaste:

• Inicio, colección, producto y carrito en escritorio y móvil.
• Cada sección personalizada en el editor de temas: agrégala, cambia sus ajustes, reordénala.
• Navegación, búsqueda, filtros y cualquier formulario o popup que personalizaste.
• Selectores de idioma y moneda si la tienda los usa.
• Apps que inyectan bloques o embeds.

Abre también la vista previa en el editor de temas. Una sección que se ve bien en la tienda puede fallar en el editor si su esquema cambió.

Paso 6: publica y conserva el rollback

Cuando staging pasa, publica desde el admin o con la CLI. El tema anterior queda en la biblioteca, así que el rollback está a una publicación de distancia. Consérvalo unas semanas y anota la fecha en el repositorio.

Una lista corta para cerrar el trabajo:

1. Inventario de personalizaciones revisado contra vendor/v1.
2. Archivos agregados, modificados y eliminados contabilizados.
3. Plantillas JSON y ajustes reconciliados con los esquemas nuevos.
4. shopify theme check sin errores.
5. Flujo completo probado en el tema sin publicar, en el editor y en la tienda.
6. Tema anterior conservado como rollback y repositorio etiquetado con ambas versiones.

Cuándo conviene pedir ayuda

Una actualización es sobre todo lectura cuidadosa. Conviene un segundo par de ojos cuando la tienda tiene muchas secciones personalizadas, cuando el proveedor reestructuró el tema entre versiones o cuando la tienda no puede permitirse un mal día de publicación.

Este es el tipo de trabajo que hago como desarrollador Shopify en CDMX, y puedes ver más en los casos de estudio, entre ellos el desarrollo de inicio y página de producto para Cream Right y los filtros de colecciones para Exclusive Iron Doors. Si tienes una actualización de tema por delante, escríbeme con la tienda y el nombre del tema.