Sección 00

Cómo leer este tutorial

Prerequisitos, mental models, ruta de estudio.

Este tutorial existe porque la mayoría del material sobre Shopify en español llega tarde, está desactualizado, o asume que el lector viene de cero sin conocimientos de programación. Vos ya sabés programar. Lo que necesitás es un mapa claro del ecosistema Shopify y suficientes ejemplos de código real para dejar de buscar en la documentación oficial cada cinco minutos.

Al terminar este tutorial vas a poder construir themes personalizados con Online Store 2.0, extender el checkout sin tocar código propietario, publicar apps embebidas en el admin de Shopify, implementar lógica de negocio con Shopify Functions, y armar un storefront headless con Hydrogen. Todo eso articulado alrededor de un único proyecto: Brew Atlas, una tienda de café de especialidad con suscripciones.

En una frase

Este tutorial cubre 18 secciones organizadas en 8 bloques temáticos. El proyecto unificador Brew Atlas acompaña cada sección con pasos concretos de construcción. A un ritmo de 1 a 2 horas diarias, el recorrido completo toma entre 3 y 4 semanas.

Prerequisitos

No se asume ningún conocimiento previo de Shopify. Sí se asume lo siguiente:

JavaScript y TypeScript a nivel intermedio — closures, async/await, módulos ES, tipos básicos de TypeScript. No hace falta saber Rust ni WebAssembly para las secciones de Functions (se explica lo necesario).
Experiencia con al menos uno entre Angular, React o Vue — el tutorial usa estos frameworks como referencia constante para mapear conceptos de Shopify. Conocer los tres no es necesario.
HTML y CSS sin drama — sabés qué es el box model, podés leer un archivo CSS sin ayuda, entendés las diferencias entre inline, block y flex.
Terminal básica — navegás directorios, ejecutás comandos npm o pnpm, sabés qué hace un script de package.json.

Nota

La documentación oficial de Shopify está en inglés. Este tutorial traduce y contextualiza los conceptos, pero vas a necesitar leer inglés técnico cuando el material lo requiera. No se va a hacer un glosario — el lenguaje de la industria es en inglés y usarlo así es parte del aprendizaje.

Desde Angular/React

A lo largo del tutorial vas a ver bloques como este que mapean un concepto de Shopify a algo que ya conocés. Liquid sections son como componentes con inputs. Metafields son como campos de un CMS tipado. Shopify Functions son como middleware que corre del lado del proveedor. El objetivo es acelerar el mapeo mental, no reemplazar el aprendizaje real.

Convención de bloques de código

El tutorial tiene cientos de bloques con comandos de terminal. No todos se ejecutan. Para que sepas exactamente cuáles tenés que correr para avanzar el proyecto Brew Atlas, cada bloque de terminal trae un badge visible en la barra de título:

Ejecutar Ejemplo · comando a ejecutar

echo “este comando avanza el proyecto Brew Atlas”

Los bloques marcados Ejecutar son los pasos concretos para construir Brew Atlas. Si los salteás, el proyecto no avanza.

Referencia Ejemplo · solo ilustrativo

shopify app generate extension —type ejemplo-ilustrativo

Los bloques marcados Referencia son ejemplos que muestran la forma del comando o variantes opcionales. No los ejecutes — no forman parte del flujo del proyecto.

Al inicio de cada sección con comandos vas a encontrar un recuadro “Qué vas a ejecutar en esta sección” que lista en orden los comandos Ejecutar del capítulo, para que tengas el panorama antes de arrancar.

Tip

En la esquina superior derecha de cada bloque hay un botón Copiar. Al copiar, el tutorial normaliza los guiones tipográficos (—, –) a guiones ASCII (--, -) para que los flags largos como --store o --template funcionen al pegarlos en la terminal. Si copiás manualmente seleccionando texto, es posible que el navegador o el sistema convierta los guiones.

Cuidado

Cuidado con los em-dash al copiar/pegar comandos. Cuando un comando se renderiza en Notion, ChatGPT, Slack o muchas webs con autocorrect, los dobles guiones -- pueden convertirse en un em-dash — (U+2014). El CLI de Shopify rechaza —flag con errores crípticos del tipo Unexpected arguments. Si un comando que copiaste de algún lado te falla, verificá con echo "comando" | cat -A — el em-dash aparece como M-bM-^@M-^T en lugar de --. Reemplazalo por -- manualmente y listo.

Cómo está estructurado

Cada sección sigue el mismo formato interno para que puedas predecir dónde encontrar qué:

Concepto — qué es, por qué existe, cuándo usarlo.
Puente mental — paralelo con Angular, React o Vue para acelerar la comprensión.
Estado 2026 — novedades, deprecaciones o cambios recientes que afectan lo que vas a construir.
Código — ejemplos reales, no pseudocódigo ni fragmentos incompletos.
Paso de Brew Atlas — implementación concreta en el proyecto unificador.
Errores comunes — los que aparecen sí o sí la primera vez que usás esta parte del ecosistema.
Checklist senior — criterios de calidad para saber que realmente dominás el tema.
Quiz — 3 a 5 preguntas de opción múltiple para confirmar que los conceptos quedaron fijados. Completarlo al 100% marca la sección como “completada” en tu progreso local.

Tip

Si ya tenés experiencia con algún tema específico, podés saltar directamente a la sección y usar el checklist senior como diagnóstico. Si lo pasás completo sin dudar, seguí adelante.

Progreso y navegación

El tutorial guarda tu progreso localmente en el navegador (localStorage — no se envía a ningún servidor). Cada sección que visitás queda marcada como “visitada” con un • en la barra lateral. Cuando completás el quiz al 100%, la sección pasa a “completada” con un ✓ y el porcentaje global se actualiza en el header.

Para despejar el área de trabajo, la barra lateral se puede ocultar con el botón Ocultar del header, o con el atajo de teclado ⌘ B (macOS) / Ctrl B (Linux/Windows).

El proyecto: Brew Atlas

Brew Atlas es una tienda ficticia de café de especialidad con modelo de suscripciones mensuales. El proyecto está diseñado para tocar todas las superficies del ecosistema Shopify sin que ninguna sección se sienta artificial o desconectada.

A lo largo del tutorial vas a construir:

Theme con Online Store 2.0 — plantillas JSON, sections personalizadas, bloques de theme, dynamic sources para metafields.
Theme App Extension — un widget de suscripción que funciona en cualquier theme sin tocar el código del theme.
App embebida en el admin — construida con Polaris y App Bridge, para gestionar las suscripciones desde el panel de Shopify.
Shopify Function en Rust — descuento automático basado en frecuencia de suscripción.
Checkout Extension — selector de frecuencia y nota personalizada directamente en el checkout.
Customer Account UI — gestión del plan de suscripción desde las nuevas cuentas de cliente.
Réplica headless en Hydrogen — el mismo storefront reconstruido con React Router v7 y la Storefront API.

El código del proyecto vive en el directorio brew-atlas/ dentro de este repositorio y crece sección por sección.

Ruta de estudio recomendada

Esta es una sugerencia de distribución semanal para alguien que dedica entre 1 y 2 horas diarias:

Semana 1 — Fundamentos y setup Secciones 00 a 03. Objetivo: tener el entorno funcionando y entender Liquid al punto de poder leer cualquier theme existente.

Semana 2 — Temas y modelado de datos Secciones 04 a 07. Objetivo: construir la primera versión del theme de Brew Atlas con secciones personalizadas y metafields.

Semana 3 — APIs y extensiones Secciones 08 a 12. Objetivo: conectar la app embebida, escribir la primera Function, y tener el checkout extension funcionando en una dev store.

Semana 4 — Headless y nivel senior Secciones 13 a 17. Objetivo: réplica headless operativa, customer account UI, performance optimizada, y lista de verificación de deploy.

Qué sistema operativo usar

El ecosistema Shopify — Node.js, Rust, toolchain de WebAssembly, Shopify CLI — asume un entorno Unix. Eso marca diferencias reales de fricción según el SO.

SO	Recomendación	Comentario
Linux (Ubuntu/Debian/Fedora/Arch)	⭐ Ideal	Experiencia nativa. `npm -g`, `rustup`, Wasm, hot reload, tunnels: todo sin drama.
macOS (Intel / Apple Silicon)	✅ Excelente	95% de la experiencia Linux con Homebrew. ARM64 (M1/M2/M3) tiene builds nativos para Shopify CLI y deps.
Windows + WSL2 (Ubuntu en WSL)	✅ Viable con gotchas	Trabajá siempre en `~/proyectos/` (filesystem Linux nativo). Evitá `/mnt/c/` — el hot reload cruzando el filesystem de Windows es extremadamente lento.
Windows nativo (PowerShell / cmd)	❌ Desaconsejado	Paths con `\`, permisos distintos, fricciones reales con Rust/Wasm para Functions. Instalá WSL2 en su lugar.

Nota

Gotchas específicos de WSL2 que vale la pena saber de antemano:

No instales Node con apt — usá nvm. Shopify CLI requiere Node 22+ en 2026 y la versión de apt suele estar atrás.
Trabajá en ~/proyectos/ (filesystem ext4 dentro de WSL), no en /mnt/c/Users/tu-usuario/.... El cross-filesystem mata el hot reload.
El puerto 9292 de shopify theme dev se reenvía automáticamente a Windows, así que lo abrís en localhost:9292 desde el browser de Windows.
El tunnel de Cloudflare para shopify app dev funciona igual que en Linux nativo.
VS Code desde Windows con la extensión “WSL” abre el proyecto en modo remoto — es la forma correcta de editar.

Tip

Si estás en Windows nativo sin WSL, la instalación de WSL2 con Ubuntu toma unos 10 minutos (wsl --install desde PowerShell como admin). Es tiempo que se amortiza en la primera semana del tutorial.

Shopify.dev — documentación oficial rev: 2026-04

Quiz

La sección que sigue, La arquitectura Shopify, presenta el mapa mental completo del ecosistema antes de tocar una sola línea de código. Es el paso más importante del tutorial: entender las cinco superficies de Shopify y cómo se relacionan entre sí.