17 · Deploy y checklist senior

Las tres rutas de distribución

Antes de hablar de review, hay que entender cuál de los tres caminos aplica a tu proyecto. La elección determina si hay un proceso de review, cuánto dura, y qué criterios aplican.

Ruta 1: App custom (privada)

Una app custom se instala en una sola tienda mediante una invitación directa del comerciante. No pasa por el App Store, no hay review pública. El comerciante va a Admin → Apps → Desarrollar apps y te da acceso, o tú generas las credenciales desde tu Partner Dashboard y compartes el link de instalación.

Esta es la ruta correcta cuando el cliente es uno solo, cuando la app contiene lógica de negocio específica de esa empresa, o cuando necesitas iterar rápido sin el ciclo de review. La desventaja: si el cliente tiene múltiples tiendas, tienes que instalar la app en cada una por separado.

Ruta 2: App pública en el App Store

Una app pública puede instalarse en cualquier tienda Shopify. Para llegar al App Store, tu app pasa por el proceso de review de Shopify — una evaluación manual que puede tomar una a tres semanas en la primera submisión. Los criterios cubren performance (Lighthouse), seguridad (HMAC, CSP), scopes (least-privilege), UX, y honestidad en los metadatos.

Una vez publicada, Shopify hace auditorías periódicas. Si tu app cae por debajo de los estándares después de publicarse, puede ser removida del App Store.

Ruta 3: Theme Store

Los themes que se venden en el Theme Store de Shopify pasan por el proceso de review más estricto del ecosistema. Los criterios incluyen accesibilidad completa (WCAG 2.2 AA), internacionalización (ningún texto hardcodeado en inglés), lógica de inventario correcta (mostrar disponibilidad real, manejar out-of-stock correctamente), documentación para el comerciante, y documentación técnica para el desarrollador. El proceso puede tomar semanas y es frecuente que el review pida cambios antes de aprobar.

Built for Shopify

Built for Shopify (BFS) es la certificación de calidad para apps embebidas en el admin de Shopify. No es un requisito para publicar en el App Store, pero es la distinción que Shopify otorga a las apps que cumplen sus más altos estándares de UX, performance, y seguridad.

Para obtener la certificación BFS, tu app embebida debe cumplir todos estos requisitos:

• Session tokens: autenticación con JWT (session tokens), no con cookies de terceros
• App Bridge: usar App Bridge v4 para la integración con el admin de Shopify — menú de navegación, modales, toasts, y comunicación con el frame del admin
• Polaris: la UI del admin está construida con componentes Polaris — no CSS propio que compita visualmente con el admin de Shopify
• Core Web Vitals: LCP, INP, y CLS dentro de los umbrales de Google en el admin iframe
• Scopes mínimos: solo los scopes de OAuth que la app realmente usa, en la cantidad mínima necesaria
• Metadatos honestos: el nombre, la descripción, y los screenshots en el App Store describen con precisión lo que la app hace — sin promesas de features que no existen
• Cleanup de datos en uninstall: el webhook app/uninstalled borra los datos del comerciante que tu app tiene en tu servidor, conforme a GDPR/CCPA

Checklist de review para apps

Antes de submittir tu app al App Store, verifica cada uno de estos puntos. Una submisión incompleta puede ser rechazada, y el ciclo de corrección y re-review puede añadir semanas al timeline.

OAuth y autenticación:

• El flujo OAuth funciona con una instalación en una tienda limpia, sin estado previo
• Todos los redirect URIs declarados en el Partner Dashboard están implementados y responden correctamente
• El PKCE flow está implementado si la app usa Shopify CLI v3 (el CLI lo configura automáticamente)

Scopes:

• Todos los scopes declarados en shopify.app.toml son usados activamente por la app
• No hay scopes declarados “por si acaso” — si un scope no se usa en el primer release, no se declara
• Si la app necesita scopes adicionales en una versión futura, los agrega con un mensaje claro al comerciante durante la actualización

Seguridad:

• Todos los webhooks validan la firma HMAC antes de procesar el payload — sin excepción
• El Content Security Policy del admin iframe está configurado correctamente (frame-ancestors https://*.shopify.com, https://admin.shopify.com)
• El token de Admin API está en variables de entorno del servidor, nunca en el código ni en el cliente
• La app no hace llamadas al Admin API antes de que el flujo de instalación esté completo (sin el access token)

Webhooks obligatorios de GDPR:

Shopify requiere que todas las apps públicas implementen tres webhooks de conformidad con GDPR y CCPA. Sin estos, la app no puede pasar el review:

• customers/data_request: el comerciante solicita exportar los datos de un cliente
• customers/redact: el comerciante solicita borrar los datos de un cliente
• shop/redact: cuando un comerciante desinstala la app, 48 horas después Shopify envía este webhook para señalar que los datos de la tienda deben borrarse

Los tres deben responder HTTP 200 dentro de los 5 segundos. La lógica real (exportar o borrar datos) puede correr en background, pero el handler debe responder inmediatamente.

Billing:

• Si la app cobra una tarifa de uso, el flujo de billing usa el Billing API de Shopify — no un procesador de pagos externo
• El periodo de prueba gratuito (si existe) está correctamente configurado en el Billing API
• La app no desactiva funcionalidades cuando el comerciante está en trial, solo cuando el trial expiró y no completó el billing

UX:

• La primera pantalla que ve el comerciante después de instalar le explica qué hace la app y cómo empezar
• Los estados de error son legibles — no dumps de JSON ni mensajes técnicos para el comerciante
• Las acciones destructivas (borrar datos, cancelar algo) tienen confirmación explícita

Checklist de review para themes

El process de review del Theme Store es más detallado que el de apps. Los auditores revisan el theme manualmente en una tienda de prueba con datos reales.

Performance:

• Lighthouse ≥ 75 en mobile con los datos de demo del theme — no en una tienda en blanco
• No hay JavaScript bloqueante en el critical path (scripts en el <head> sin async o defer)
• Las imágenes del theme usan el filtro image_url: width: con los atributos width y height correctos
• El theme no carga recursos de terceros externos en el critical path (fuentes de Google Fonts sin preconnect, etc.)

Accesibilidad:

• Navegación completa por teclado: menú, carrito, modales, dropdowns
• Contraste WCAG 2.2 AA: relación ≥ 4.5:1 para texto normal, ≥ 3:1 para texto grande
• Todos los inputs tienen labels o aria-label
• Skip-to-content link visible cuando recibe foco
• ARIA solo cuando HTML nativo no puede expresar la semántica necesaria
• Target size mínimo de 24x24px para elementos interactivos (criterio nuevo de WCAG 2.2)

Internacionalización:

• No hay textos hardcodeados en los archivos .liquid — todos usan {{ 'key' | t }}
• Los archivos de locale cubren todos los strings de UI
• El theme maneja RTL correctamente cuando el locale es árabe o hebreo
• Los precios usan el filtro | money para que Shopify aplique el formato correcto

Inventario:

• Los productos out-of-stock muestran un estado claro (“Agotado”, “Sin stock”)
• El botón “Agregar al carrito” está deshabilitado correctamente cuando no hay inventario
• La lógica de variantes muestra correctamente qué combinaciones están disponibles vs. agotadas

Documentación:

• Guía para el comerciante: cómo personalizar el theme desde el editor visual
• Guía técnica: cómo instalar, cómo manejar actualizaciones de Shopify, qué customizaciones son soportadas

Metadata:

• Nombre y descripción del theme describen con precisión lo que ofrece
• Los screenshots muestran el theme con datos reales, no placeholders
• Sin emojis en el nombre ni en la descripción del Theme Store

Debugging en producción

Cuando algo falla en producción, el flujo de diagnóstico tiene un orden:

1. Partner Dashboard → Events

El primer lugar para ir. El dashboard de events muestra un timeline de webhooks recibidos, errores de API, y eventos de la app en las últimas 72 horas. Filtrar por tienda y por tipo de evento. Si un webhook falló repetidamente, acá está la evidencia.

2. requestId en las respuestas del Admin API

Cada respuesta del Admin API incluye el header X-Request-Id. Cuando reportas un error a Shopify Support, ese requestId es lo que les permite rastrear la request en sus sistemas. Loguea ese header en todas las respuestas de Admin API — es la diferencia entre “algo falló” y “la request ABC123 falló a las 14:32 UTC con este error”.

// Loguear requestId en cada respuesta
const response = await fetch(adminApiUrl, { headers });
const requestId = response.headers.get('x-request-id');
console.log({ requestId, status: response.status });

3. Rate limit: backoff sobre 429

Un 429 del Admin API significa que agotaste el bucket de costo. No reintentes inmediatamente — el header Retry-After te dice cuántos segundos esperar. El backoff exponencial con jitter es el estándar: esperar Math.pow(2, attempt) * 1000 + Math.random() * 500 ms antes de reintentar. Después de 5 reintentos, loguear como error crítico y alertar.

4. Errors en Oxygen (Hydrogen)

Los errores de loader en Hydrogen que llegan a un throw new Response(...) son capturados por el Error Boundary del componente padre. Los errores no capturados muestran la pantalla de error de Oxygen. Configurar sentry o equivalente para capturar errores de runtime antes de que lleguen al usuario.

Versionado y rollback

Apps: cada shopify app deploy crea una nueva versión inmutable. Para hacer rollback, redespliegas una versión anterior (por tag de git o por el ID de versión en el Partner Dashboard). El comerciante no nota el rollback si la app sigue respondiendo correctamente.

Themes: el Theme Store tiene un sistema de versiones con un botón “Release” que hace swap entre la versión publicada y la anterior. Para tiendas individuales (no Theme Store), shopify theme push actualiza el theme activo. El rollback es hacer push de la versión anterior.

Hydrogen/Oxygen: los environments de Oxygen son inmutables. Cada deploy crea un nuevo environment de preview. La promoción de preview a producción hace swap en el routing de Oxygen. El ambiente anterior de producción queda como snapshot — para rollback, promueves ese snapshot de vuelta a producción desde el dashboard.

Deprecación responsable

Cuando remueves una feature de una app, el proceso correcto es:

1. Version N: deprecar la feature — agregar un banner en el admin de la app indicando que la feature se eliminará en 60 días. Si la feature tiene una alternativa, linkear a ella.
2. Transition N a N+3: mantener la feature funcional pero deprecada. Los eventos de analytics pueden ayudar a medir cuántos comerciantes la están usando activamente.
3. Version N+3 mínimo: remover la feature del código. Si la feature manipulaba datos (por ejemplo, guardaba registros en una tabla de tu base de datos), correr una migration que mueva esos datos a la nueva estructura o que los borre limpiamente.

Para features que requieren migración de datos, la herramienta es una bulk mutation del Admin API que procesa los recursos afectados en un job de una sola ejecución. Documentarlo en el changelog para el comerciante.

Puentes mentales

Estado 2026

Lo relevante al 2026:

• Built for Shopify es incremental: Shopify introdujo un programa de certificación gradual. Podés publicar en el App Store sin BFS, y después trabajar hacia la certificación BFS como mejora post-lanzamiento.
• GDPR webhooks son no-negociables: desde 2022, todas las apps públicas deben tener los tres webhooks GDPR implementados. El review los verifica explícitamente. Una app sin ellos es rechazada en la primera review.
• App Bridge v4: la versión 4 de App Bridge eliminó la dependencia de Shopify/App Bridge anterior. Los componentes de App Bridge v4 son componentes de Polaris — si tienes una app embebida en v3 o anterior, planifica la migración.
• WCAG 2.2 (para themes): el Theme Store actualiza sus requerimientos de accesibilidad a medida que el estándar evoluciona. Al momento de escribir esto (2026-04), el estándar vigente es WCAG 2.2 AA.

Proyecto · Brew Atlas

shopify theme push --live

shopify app deploy

shopify hydrogen link
shopify hydrogen deploy

El checklist senior

Este es el checklist que define el perfil senior Shopify. No es un checklist de “sé la documentación” — es un checklist de “puedo construir y razonar sobre” cada una de estas capacidades. Si puedes marcar todos los ítems con evidencia concreta (un proyecto, un fragmento de código, un diagnóstico resuelto), tienes el perfil senior.

Cierre

Terminaste de recorrer todo el camino que promete tu CV. Si puedes armar Brew Atlas de principio a fin — theme OS 2.0, theme app extension, admin app embebida, Shopify Function en Rust, checkout extension, customer account extension, y la réplica headless en Hydrogen — tienes la base senior. El siguiente paso es construir el proyecto real: recrea Brew Atlas en tu dev store, llévalo a producción, y documenta cada decisión. Cuando apliques, esa evidencia vale más que cualquier descripción del CV.

Los links oficiales al final de cada sección son tu referencia canónica. shopify.dev cambia, este tutorial es del 2026-04 — siempre valida versiones antes de ejecutar.