Saltar al contenido

Theme app extensions de Shopify: tu app no debería tocar el código del tema

En la práctica/ 12 min de lectura

Theme app extensions de Shopify en la práctica: app blocks contra app embeds, una extensión completa con Shopify CLI, el fin de los script tags y las reglas de la App Store.

  • Shopify
  • Apps de Shopify
  • Temas
En este artículo (9)
  1. El problema del código que se queda
  2. App blocks contra app embeds
  3. Crear la extensión con Shopify CLI
  4. Lo que gana el comerciante
  5. Cómo limpiar el código viejo de tu app
  6. Requisitos de la App Store de Shopify para theme app extensions
  7. Errores comunes
  8. Preguntas frecuentes
  9. Checklist

Las theme app extensions de Shopify son la forma de que tu app agregue contenido o scripts a una tienda sin editar el código del tema. Entregas app blocks y app embeds, el comerciante los activa desde el editor de temas y Shopify los quita cuando desinstala la app. La App Store las exige.

Aquí tienes una extensión completa de ejemplo (un aviso de existencias bajas y una burbuja de ayuda), cómo generarla con Shopify CLI, qué hacer con los script tags que tu app ya instaló y los requisitos vigentes. Pasamos la extensión por shopify theme check en local, sin conectarla a ninguna tienda.

El problema del código que se queda

Durante años, integrar una app con una tienda significaba una de dos cosas: escribir un snippet en snippets/ con la Asset API y editar theme.liquid o la plantilla de producto para renderizarlo, o registrar un script tag que cargaba JavaScript remoto en todas las páginas. La guía de migración de Shopify le pone nombre al resultado: código fantasma. Desinstalar la app suele dejar esas ediciones en el tema, con problemas de calidad y rendimiento, y saca al tema de su ruta de actualización. Según la documentación de integración con la tienda, al quitar ese código a mano basta un salto de línea o un espacio de más para que el tema pierda esa ruta.

Si ya sufriste esto como comerciante, el artículo sobre cómo medir el peso de las apps de Shopify explica cómo encontrar y limpiar lo que dejaron. Este va del otro lado: lo que tiene que hacer quien construye la app para no dejar nada.

Además, los script tags tienen fecha de cierre. Según la página de script tags en la tienda, consultada el 19 de noviembre de 2026:

  • Desde el 1 de octubre de 2026 no puedes crear ni actualizar script tags: scriptTagCreate y scriptTagUpdate devuelven un error de permisos en todas las versiones de la API. Fijar una versión vieja no lo evita.
  • En la página de estado del pedido dejaron de funcionar el 26 de agosto de 2026.
  • El 1 de marzo de 2027 Shopify deja de inyectarlos en las páginas de la tienda. Leer y borrar sigue funcionando hasta entonces.
dónde vive el código de la appantes: la app edita el temalayout/theme.liquid+ <script> pegado a manosnippets/app-badge.liquidescrito por la Asset APIsections/main-product.liquid+ {% render 'app-badge' %}script tagJS remoto en cada páginaal desinstalar: el código se quedacon theme app extensiontema: sin cambiossigue en su ruta de actualizaciónblocks/stock-badge.liquidapp block, lo agrega el comercianteblocks/help-bubble.liquidapp embed, se activa en el editorassets/help-bubble.jsdesde el CDN de Shopifyal desinstalar, Shopify los quitascript tags: sin altas desde el 1 oct 2026dejan de cargar en la tienda el 1 de marzo de 2027 · fuente: shopify.dev

Desliza la figura para verla completa

App blocks contra app embeds

Una theme app extension es un paquete de app blocks, app embed blocks, assets y snippets. La diferencia entre los dos tipos de bloque la marca el valor de target en el schema, según la documentación de configuración:

App blockApp embed
targetcontent (section es el valor antiguo, sigue funcionando)head, compliance_head o body
Dónde apareceDentro de una sección, donde el comerciante lo pongaAntes de </head> o de </body>
TemasSolo Online Store 2.0: plantillas JSON y secciones que aceptan bloques @appVintage y Online Store 2.0
DatosPuede apuntar a fuentes dinámicas con autofillSolo el ámbito global de Liquid de la página
Tras instalarNo está en el tema hasta que el comerciante lo agregaDesactivado hasta que el comerciante lo activa
ParaReseñas, estrellas, avisos en la ficha de productoChats, insignias flotantes, píxeles, metaetiquetas

La regla corta: si tu app pinta algo dentro de la página, app block; si flota encima, no tiene interfaz o solo carga JavaScript, app embed. compliance_head se incluye antes que los demás y Shopify pide usarlo solo cuando haga falta, por ejemplo en un banner de cookies. Ningún bloque se renderiza en las páginas del checkout; para eso existen otras extensiones.

dos tipos de bloque en la misma extensiónapp blockapp embedtargetcontenthead · compliance_head · bodydóndedentro de una secciónantes de </head> o </body>temassolo Online Store 2.0vintage y Online Store 2.0datosfuentes dinámicas (autofill)solo ámbito global de Liquidal instalarlo agrega el comerciantedesactivado hasta activarloparareseñas, avisos de productochats, insignias, píxelesninguno de los dos se renderiza en las páginas del checkoutel target del schema decide el tipofuente: shopify.dev, configurar theme app extensions

Desliza la figura para verla completa

Crear la extensión con Shopify CLI

Desde la carpeta de tu app, la guía de inicio usa un comando interactivo. Con banderas queda así (el identificador de la plantilla lo sacamos del código de Shopify CLI 3.88.1):

shopify app generate extension --template theme_app_extension --name stock-badge

extensions/stock-badge
├── assets/          stock-badge.css, help-bubble.css, help-bubble.js
├── blocks/          stock-badge.liquid, help-bubble.liquid
├── snippets/
├── locales/         en.default.json, es.json, en.default.schema.json, es.schema.json
└── shopify.extension.toml
  1. --template theme_app_extension elige el tipo; sin la bandera, la CLI te lo pregunta. --name es el nombre de la carpeta y de la extensión.
  2. assets/ guarda CSS, JavaScript e imágenes, que Shopify sirve desde su CDN.
  3. blocks/ guarda los archivos Liquid de cada app block y app embed. El nombre del archivo es el handle del bloque.
  4. snippets/ guarda Liquid reutilizable entre bloques; locales/, las traducciones para la tienda y para el editor.
  5. shopify.extension.toml solo lleva name y type = "theme": el comportamiento lo definen los schemas.

La plantilla generada trae un ejemplo de estrellas que necesita un metafield demo.avg_rating; lo cambiamos por estos dos bloques. El primero es el app block del aviso de existencias:

{%- liquid
  assign badge_product = block.settings.product
  assign variant = badge_product.selected_or_first_available_variant
  assign quantity = variant.inventory_quantity
-%}
{%- if variant.inventory_management == 'shopify' and quantity > 0 and quantity <= block.settings.threshold -%}
  <p class="stock-badge" style="--stock-badge-color: {{ block.settings.color }}">
    {{ 'stock_badge.low_stock' | t: quantity: quantity }}
  </p>
{%- endif -%}

{% schema %}
{
  "name": "t:blocks.stock_badge.name",
  "target": "content",
  "stylesheet": "stock-badge.css",
  "enabled_on": { "templates": ["product"] },
  "settings": [
    { "type": "product", "id": "product", "label": "t:blocks.stock_badge.product", "autofill": true },
    { "type": "range", "id": "threshold", "label": "t:blocks.stock_badge.threshold", "min": 1, "max": 20, "step": 1, "default": 5 },
    { "type": "color", "id": "color", "label": "t:blocks.stock_badge.color", "default": "#b42318" }
  ]
}
{% endschema %}
  1. El bloque liquid toma el producto del ajuste product. Como ese ajuste lleva autofill, Shopify lo llena solo con el producto de la sección donde se agrega el bloque.
  2. selected_or_first_available_variant es la variante elegida en la URL o la primera disponible.
  3. La condición pide inventory_management == 'shopify' porque, según la referencia de Liquid, si el inventario no se rastrea, inventory_quantity devuelve las unidades vendidas y el aviso mentiría.
  4. El texto sale de locales/ con el filtro t, así que la tienda lo muestra en su idioma. El color pasa como variable CSS.
  5. "target": "content" lo convierte en app block; enabled_on lo limita a la plantilla de producto.
  6. stylesheet carga assets/stock-badge.css solo en las páginas donde está el bloque.
  7. Las etiquetas t: salen de en.default.schema.json y es.schema.json: el editor muestra los ajustes en el idioma del comerciante.

El segundo es el app embed. Su schema es lo importante:

{% schema %}
{
  "name": "t:blocks.help_bubble.name",
  "target": "body",
  "javascript": "help-bubble.js",
  "stylesheet": "help-bubble.css",
  "enabled_on": { "templates": ["product", "collection"] },
  "settings": [
    { "type": "url", "id": "link", "label": "t:blocks.help_bubble.link" },
    { "type": "text", "id": "label", "label": "t:blocks.help_bubble.label", "default": "Help" }
  ]
}
{% endschema %}
  1. "target": "body" lo convierte en app embed: Shopify inyecta su HTML antes de </body>.
  2. javascript carga assets/help-bubble.js solo si el embed está activo en esa página. Si varios bloques usan el mismo archivo, se incluye una vez.
  3. enabled_on limita el embed a producto y colección. Shopify lo señala como la ventaja frente al script tag, que no podía cargar solo en algunas páginas.
  4. Los ajustes son los mínimos: un enlace y un texto. La guía de UX pide no llenar el panel de embeds de opciones.

Lo validamos con shopify theme check --path extensions/stock-badge: «6 files inspected with no offenses found». En una copia rota marcó el CSS que no existía, la clave de traducción que faltaba y una etiqueta sin cerrar. No marcó un target inventado, así que ese valor revísalo tú. Para ver la extensión en una tienda de desarrollo, shopify app dev (la vista previa solo funciona en Chrome); para publicarla, shopify app deploy, que crea una versión de la app. shopify app build corre Theme Check y los límites antes de desplegar:

LímiteValorTipo
Todos los archivos de la extensión10 MBObligatorio
Bloques30Obligatorio
Archivos de locales / tamaño de cada uno100 / 15 KBObligatorio
Liquid en todos los archivos100 KBObligatorio
CSS comprimido referido en el schema100 KBSugerido
JS comprimido referido en el schema10 KBSugerido

Lo que gana el comerciante

  • Su tema queda intacto. La app no edita archivos, así que el tema sigue en su ruta de actualización.
  • Decide dónde va cada cosa. Agrega, quita y mueve app blocks desde la sección Apps del editor, activa o desactiva embeds en App embeds y lo previsualiza antes de guardar.
  • Puede apagar tu app sin escribirte. El embed aparece en el editor, donde se ve que tu app está corriendo y se puede desactivar.
  • Desinstalar limpia. La guía de UX dice que al desinstalar, los bloques de la app se quitan del tema de forma automática y completa.
  • Menos peso. Los assets salen del CDN de Shopify y los scripts cargan solo en las plantillas que eliges.

Un bloque también puede mostrar contenido que el comerciante edita en el admin: con los prefijos reservados $app:, lee metafields y metaobjetos de tu app sin escribir su ID a mano. Si quieres ese patrón, revisa metaobjetos para contenido editable. Y si tu script recalculaba precios o descuentos en el carrito con JavaScript, esa lógica no va en un embed: va en Shopify Functions.

Ojo con un detalle: un app embed se activa por tema. Si la tienda publica otro tema, tu embed no está activo en él y hay que volver a activarlo.

el comerciante activa los bloques en el editorplantilla: productoInformación del productoTítuloPrecioAviso de existenciasapp+ Agregar bloque › Appsapp embedsBurbuja de ayudavista previaQuedan 3 en existenciaAyuda ×el comerciante decide dónde y cuándoilustrativo: los dos bloques de este artículo, sin tocar el tema

Desliza la figura para verla completa

Cómo limpiar el código viejo de tu app

Si tu app ya está instalada con script tags o con snippets escritos por la Asset API, la migración tiene un orden. Los embeds empiezan desactivados y tu app no puede activarlos por el comerciante, así que si borras el script tag antes, la función desaparece hasta que alguien active el embed:

  1. Publica la extensión con un app embed que haga lo que hacía el script tag.
  2. Manda al comerciante al editor con el embed ya activado mediante un enlace directo: https://<tienda>.myshopify.com/admin/themes/current/editor?context=apps&template=product&activateAppId={api_key}/help-bubble, donde api_key es el client_id de tu shopify.app.toml y help-bubble el nombre del archivo del bloque.
  3. Confirma que está activo: app.extensions() desde tu app en el admin devuelve active o available por bloque; desde el backend, lee config/settings_data.json del tema publicado con el permiso read_themes.
  4. Borra el script tag. Si conviven, el script carga dos veces: eventos de analítica duplicados o la interfaz pintada dos veces.

Para encontrar y borrar los script tags de tu app, con el token que ya tiene en esa tienda:

query AppScriptTags {
  scriptTags(first: 50) {
    nodes { id src displayScope createdAt }
  }
}

mutation DeleteScriptTag($id: ID!) {
  scriptTagDelete(id: $id) {
    deletedScriptTagId
    userErrors { field message }
  }
}
  1. scriptTags devuelve solo los script tags de tu app, hasta 50 por página.
  2. src te dice qué archivo carga cada uno y displayScope dónde corre; si es order_status o all, esa parte ya dejó de funcionar.
  3. scriptTagDelete recibe el id y pide el permiso write_script_tags.
  4. userErrors llega vacío si salió bien; revísalo antes de dar la tienda por migrada.

Lo que la Asset API escribió en el tema no se va solo. La guía de migración pide que, si el tema publicado acepta app blocks, tu app deje de hacer cualquier POST a Asset y a ScriptTag, y la de integración pide darle al comerciante instrucciones para quitar ese código por completo. Ponlas en tu pantalla de bienvenida, junto al enlace directo; si la construyes con Polaris, quedan dentro del admin como el resto de tu app. Una excepción: las apps personalizadas creadas desde el admin no pueden usar extensiones; ahí el script va en un bloque de Liquid personalizado del tema.

Requisitos de la App Store de Shopify para theme app extensions

La sección 5.1 de los requisitos de la App Store, consultados el 19 de noviembre de 2026, dice que los temas se modifican solo con theme app extensions:

  • 5.1.1. Si tu app modifica el tema, debe usar theme app extensions. Ni tú ni el comerciante deben hacer cambios de código en el tema.
  • 5.1.2. El widget debe verse bien y sin errores en el editor de temas y en la tienda.
  • 5.1.3. La app debe traer instrucciones detalladas para instalar sus app embeds y app blocks; Shopify recomienda con fuerza un enlace directo.

La guía de UX agrega dos cosas que revisan: la descripción de la app debe decir si necesita un tema Online Store 2.0, y el nombre de cada bloque debe tener menos de 25 caracteres y no repetir el nombre de la app, que el editor ya muestra debajo.

Errores comunes

  • Borrar el script tag antes de que el embed esté activo. La tienda se queda sin la función hasta que el comerciante entra al editor.
  • Dejar los dos activos. El script corre dos veces y duplica eventos.
  • Usar "target": "section" en bloques nuevos. Funciona, pero es el valor antiguo: usa content.
  • Un app block para algo que flota. Un chat o una insignia flotante son embeds; un app block exige tema Online Store 2.0.
  • Esperar fuentes dinámicas en un embed. Solo ve el ámbito global de Liquid; para el producto de la sección, app block con autofill.
  • Leer inventory_quantity sin comprobar el rastreo. Sin rastreo devuelve las unidades vendidas.
  • Olvidar que el embed es por tema. Si la tienda cambia de tema, compruébalo otra vez.

Preguntas frecuentes

¿Las theme app extensions funcionan en temas vintage?

Los app embeds sí, porque no dependen de secciones ni de plantillas JSON. Los app blocks no: necesitan plantillas JSON y secciones que acepten bloques @app.

¿Qué pasa con mi extensión cuando el comerciante desinstala la app?

Según la guía de UX de Shopify, los bloques asociados a la app se quitan del tema de forma automática y completa. Lo que tu app haya escrito con la Asset API no entra en eso.

¿Puedo seguir usando script tags?

Desde el 1 de octubre de 2026 no puedes crear ni actualizar ninguno, y el 1 de marzo de 2027 dejan de cargarse en la tienda. Para cargar JavaScript, usa un app embed; si solo recoges analítica, un web pixel.

¿Necesito publicar en la App Store para usarlas?

No. Cualquier app creada con Shopify CLI o el Dev Dashboard puede tener extensiones, incluidas las apps a medida. La excepción son las apps personalizadas creadas directamente en el admin.

Checklist

  • La app no escribe en el tema con la Asset API ni crea script tags.
  • El contenido en la página es app block con "target": "content"; lo flotante o sin interfaz, app embed.
  • Los app blocks de producto usan autofill y enabled_on.
  • El JavaScript va en assets/ y se carga con javascript solo en las plantillas necesarias.
  • Los textos salen de locales/, para la tienda y para el editor.
  • shopify theme check pasa sin errores y la extensión cabe en los límites.
  • La pantalla de bienvenida explica cómo activar los bloques y trae el enlace directo.
  • Los script tags se borran solo después de confirmar que el embed está activo.

Una app que no toca el tema también es más fácil de quitar, y eso cuenta cuando el comerciante decide si construir una app a medida o instalar una del store.

¿Viste esto en Instagram? Todas las guías de los Reels están en ecomlabs.dev/guias.

Escrito por

Luis Morales

Luis Morales

Desarrollador frontend y Shopify, EcomLabs

@luismoralesdev en Instagram

Publicado el 19 de noviembre de 2026 · actualizado el 20 de noviembre de 2026

← Blog