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)
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:
scriptTagCreateyscriptTagUpdatedevuelven 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.
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 block | App embed | |
|---|---|---|
target | content (section es el valor antiguo, sigue funcionando) | head, compliance_head o body |
| Dónde aparece | Dentro de una sección, donde el comerciante lo ponga | Antes de </head> o de </body> |
| Temas | Solo Online Store 2.0: plantillas JSON y secciones que aceptan bloques @app | Vintage y Online Store 2.0 |
| Datos | Puede apuntar a fuentes dinámicas con autofill | Solo el ámbito global de Liquid de la página |
| Tras instalar | No está en el tema hasta que el comerciante lo agrega | Desactivado hasta que el comerciante lo activa |
| Para | Reseñas, estrellas, avisos en la ficha de producto | Chats, 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.
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
--template theme_app_extensionelige el tipo; sin la bandera, la CLI te lo pregunta.--namees el nombre de la carpeta y de la extensión.assets/guarda CSS, JavaScript e imágenes, que Shopify sirve desde su CDN.blocks/guarda los archivos Liquid de cada app block y app embed. El nombre del archivo es el handle del bloque.snippets/guarda Liquid reutilizable entre bloques;locales/, las traducciones para la tienda y para el editor.shopify.extension.tomlsolo llevanameytype = "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 %}
- El bloque
liquidtoma el producto del ajusteproduct. Como ese ajuste llevaautofill, Shopify lo llena solo con el producto de la sección donde se agrega el bloque. selected_or_first_available_variantes la variante elegida en la URL o la primera disponible.- La condición pide
inventory_management == 'shopify'porque, según la referencia de Liquid, si el inventario no se rastrea,inventory_quantitydevuelve las unidades vendidas y el aviso mentiría. - El texto sale de
locales/con el filtrot, así que la tienda lo muestra en su idioma. El color pasa como variable CSS. "target": "content"lo convierte en app block;enabled_onlo limita a la plantilla de producto.stylesheetcargaassets/stock-badge.csssolo en las páginas donde está el bloque.- Las etiquetas
t:salen deen.default.schema.jsonyes.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 %}
"target": "body"lo convierte en app embed: Shopify inyecta su HTML antes de</body>.javascriptcargaassets/help-bubble.jssolo si el embed está activo en esa página. Si varios bloques usan el mismo archivo, se incluye una vez.enabled_onlimita 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.- 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ímite | Valor | Tipo |
|---|---|---|
| Todos los archivos de la extensión | 10 MB | Obligatorio |
| Bloques | 30 | Obligatorio |
| Archivos de locales / tamaño de cada uno | 100 / 15 KB | Obligatorio |
| Liquid en todos los archivos | 100 KB | Obligatorio |
| CSS comprimido referido en el schema | 100 KB | Sugerido |
| JS comprimido referido en el schema | 10 KB | Sugerido |
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.
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:
- Publica la extensión con un app embed que haga lo que hacía el script tag.
- 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, dondeapi_keyes elclient_idde tushopify.app.tomlyhelp-bubbleel nombre del archivo del bloque. - Confirma que está activo:
app.extensions()desde tu app en el admin devuelveactiveoavailablepor bloque; desde el backend, leeconfig/settings_data.jsondel tema publicado con el permisoread_themes. - 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 }
}
}
scriptTagsdevuelve solo los script tags de tu app, hasta 50 por página.srcte dice qué archivo carga cada uno ydisplayScopedónde corre; si esorder_statusoall, esa parte ya dejó de funcionar.scriptTagDeleterecibe elidy pide el permisowrite_script_tags.userErrorsllega 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: usacontent. - 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_quantitysin 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
autofillyenabled_on. - El JavaScript va en
assets/y se carga conjavascriptsolo en las plantillas necesarias. - Los textos salen de
locales/, para la tienda y para el editor. shopify theme checkpasa 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

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