02 · Setup profesional

Qué SO usar

El ecosistema (Node, Rust, toolchain de Wasm, Shopify CLI) asume Unix. Según el SO, la fricción cambia.

Qué es y por qué existe

El ecosistema Shopify distingue entre dos tipos de cuentas desde el principio, y la confusión entre ellas genera problemas reales. Una cuenta de comerciante es para alguien que tiene una tienda y vende productos. Una Partner account es para desarrolladores, agencias y cualquiera que construya para otros comerciantes o para el App Store. Tú necesitas una Partner account.

La diferencia no es solo administrativa. Con una Partner account puedes crear development stores: tiendas de prueba gratuitas que no expiran, donde puedes instalar tu theme o app, generar órdenes de prueba con tarjetas de crédito falsas, y probar integraciones sin pagar ni arriesgar datos reales. Un comerciante con cuenta estándar no puede crear development stores.

Shopify CLI 3.x es el punto de entrada a todo lo demás. Maneja el scaffold de themes y apps, levanta el dev server con hot reload, abre un tunnel de Cloudflare automáticamente para que tu app localhost sea accesible desde el browser del store, y gestiona el deploy a Shopify. En versiones anteriores del CLI (1.x, 2.x), había que configurar ngrok manualmente o usar workarounds. En 3.x, el tunnel es automático y transparente.

Paso 0: Preparar directorio de trabajo

Todo el tutorial asume ~/proyectos/shopify/brew-atlas/ como directorio raíz del proyecto, tanto en macOS como en Linux y WSL2-Linux. Antes de cualquier comando del CLI, crea esa carpeta y posiciónate en ella:

Desde ~/:

mkdir -p ~/proyectos/shopify/brew-atlas
cd ~/proyectos/shopify/brew-atlas

A partir de acá, todos los comandos del CLI en esta sección asumen que el cwd es ~/proyectos/shopify/brew-atlas/ o un subdirectorio de ahí. Cuando sea relevante, lo marcamos con una línea “Desde path/:” justo antes del bloque.

Paso 1: Partner account

Ve a partners.shopify.com y crea tu cuenta. Si ya tienes una cuenta de comerciante con el mismo email, el proceso te pedirá que las vincules — Shopify soporta que el mismo email sea Partner y comerciante al mismo tiempo.

La Partner account no tiene costo. Una vez creada, tienes acceso al Partner Dashboard donde gestionas tus apps, themes, development stores y ganancias de revenue share.

Paso 2: Development store

Desde el Partner Dashboard, ve a Stores > Add store > Development store. Dale un nombre — para este tutorial usa brew-atlas-dev — y selecciona “Create a store to test and build”. Shopify te asigna un dominio brew-atlas-dev.myshopify.com que usarás en los comandos del CLI.

Los development stores son completamente funcionales: tienen todos los features de Shopify, incluyendo checkout, customer accounts, metafields y todo lo que cubre este tutorial. La única limitación relevante para nosotros es que no se pueden usar como staging para producción — están diseñadas para desarrollo.

Paso 3: Shopify CLI 3.x

npm install -g @shopify/cli@latest

Verifica que instaló correctamente:

shopify version

Deberías ver algo como @shopify/cli/3.x.x. Si ves un error de permisos en Linux/macOS, el problema es con los permisos globales de npm — usa nvm para gestionar Node y evita instalar paquetes globales con sudo.

Una vez instalado, autentícate contra tu Partner account:

shopify auth login

Esto abre el browser y te pide autorizar el CLI. Después de autorizar, el CLI guarda el token localmente y ya no te vuelve a pedir login (hasta que el token expire o lo revoques).

Paso 4: VS Code

Dos extensiones son suficientes para trabajar bien:

• Shopify Liquid — la extensión oficial de Shopify para VS Code. Da syntax highlighting para Liquid, autocompletado de tags y filters, y validación de schemas de secciones. Búscala como “Shopify Liquid” en el marketplace, publicada por Shopify.
• GraphQL Foundation — syntax highlighting y validación de queries GraphQL. La necesitarás para las secciones de APIs.

Si usas un editor diferente, Shopify mantiene un Language Server Protocol (LSP) para Liquid que funciona con cualquier editor que soporte LSP.

Paso 5: Scaffold del theme

El scaffold del theme de Brew Atlas se genera con el CLI clonando el tema Horizon de Shopify (el tema de referencia de 2025 construido sobre theme blocks):

Desde ~/proyectos/shopify/brew-atlas/:

shopify theme init brew-atlas-theme —clone-url https://github.com/Shopify/horizon

El CLI crea la carpeta brew-atlas-theme/ como subdirectorio del cwd. Si estás parado en ~/proyectos/shopify/brew-atlas/, el resultado es ~/proyectos/shopify/brew-atlas/brew-atlas-theme/ — exactamente donde queremos que viva.

Alternativamente, puedes usar el tema en blanco que provee el CLI si prefieres empezar desde cero sin las opiniones de Horizon:

Desde ~/proyectos/shopify/brew-atlas/:

shopify theme init brew-atlas-theme

Para este tutorial usamos la opción de Horizon porque ya implementa theme blocks — el primitivo actual — y podemos modificarlo en lugar de construir todo desde cero.

El directorio generado tiene la estructura estándar de un OS 2.0 theme. La sección 04 cubre esa estructura en detalle.

Paso 6: Scaffold de la app

El scaffold de la app de Brew Atlas usa el template de Remix, que desde finales de 2025 genera un proyecto con React Router v7:

Desde ~/proyectos/shopify/brew-atlas/:

npm init @shopify/app@latest — —template remix

El CLI te pedirá un nombre para la app (usa brew-atlas-app). El CLI crea la carpeta brew-atlas-app/ como subdirectorio del cwd — igual que con el theme, el resultado queda en ~/proyectos/shopify/brew-atlas/brew-atlas-app/. Cuando termine, el proyecto generado usa React Router v7 a pesar de que la opción se llama “remix” — es un naming legacy que el CLI mantiene por compatibilidad.

Paso 7: Dev server del theme

Para desarrollar el theme con hot reload:

Desde ~/proyectos/shopify/brew-atlas/brew-atlas-theme/:

shopify theme dev —store brew-atlas-dev.myshopify.com

El CLI sube el theme a tu development store en modo “preview” y abre una URL de preview en el browser. Cada vez que guardas un archivo, el CLI detecta el cambio, sincroniza el archivo modificado al store, y el browser recarga la sección afectada sin recargar la página completa.

La primera vez que ejecutas este comando, el CLI te pide autorizar el acceso al store. Autoriza, y el token queda guardado para ese store específico.

Los dos “passwords” alrededor de shopify theme dev

Si buscas “shopify theme dev password” vas a encontrar dos cosas distintas que suenan parecido. Conviene separarlas antes de que te topes con el problema:

Storefront password (candado público de la tienda)

Es el candado que aparece cuando el dev store todavía no está abierto al público: el visitante ve una pantalla pidiendo una contraseña antes de poder ver la tienda. Se gestiona en Online Store → Preferences → Password protection.

El CLI lo bypassea automáticamente si la tienda está asociada a tu Partner account — el caso típico del lector de este tutorial. No hay que hacer nada al respecto. Solo lo vas a tocar cuando decidas abrir el dev store al público manualmente.

Theme Access token (app oficial “Shopify Theme Access”)

Es un token del tipo shptka_... que se genera instalando la app oficial Shopify Theme Access en una tienda. Solo es necesario en tres escenarios:

• La tienda no está asociada a tu Partner account (por ejemplo, estás colaborando con un cliente y te pasaron un token en lugar de acceso directo).
• La cuenta tiene 2FA y el flujo interactivo del CLI te está friccionando.
• Estás corriendo el CLI en CI/CD y no hay browser disponible para shopify auth login.

Se usa pasándoselo al CLI con --password o exportando SHOPIFY_CLI_THEME_TOKEN:

shopify theme dev —store mi-store.myshopify.com —password shptka_xxxxxxxxxxxxxxxxxx

Paso 8: Tunneling automático

Cuando desarrollas una app (no un theme), tu servidor corre en localhost pero necesita ser accesible desde el browser del store de Shopify y desde los webhooks de Shopify. En versiones anteriores del CLI, esto requería configurar ngrok manualmente. En CLI 3.x, el tunnel es automático:

Desde ~/proyectos/shopify/brew-atlas/brew-atlas-app/:

shopify app dev

El CLI levanta tu servidor local y simultáneamente crea un tunnel de Cloudflare que expone localhost:3000 (o el puerto que uses) en una URL pública *.trycloudflare.com. Esa URL se registra automáticamente como la URL de tu app en el Partner Dashboard para el store conectado. No tienes que tocar la configuración del tunnel.

El flujo de trabajo diario

Una vez que tienes el entorno configurado, el ciclo de desarrollo diario es:

Para el theme:

Desde ~/proyectos/shopify/brew-atlas/brew-atlas-theme/:

shopify theme dev —store brew-atlas-dev.myshopify.com

Editas archivos localmente, el CLI los sincroniza al store, ves los cambios en el browser. Cuando terminas, el CLI ofrece publicar el theme como draft o como theme activo.

Para la app:

Desde ~/proyectos/shopify/brew-atlas/brew-atlas-app/:

shopify app dev

El CLI levanta el servidor (que es tu app de React Router v7), abre el tunnel, y conecta la app al store. Las rutas de la app aparecen en el admin del store dentro del iframe de la embedded app.

Puentes mentales

Estado 2026

El CLI 3.x está en activo desarrollo. Los cambios más relevantes de los últimos meses:

• El template “remix” genera proyectos con React Router v7 desde Q4 2025. El naming no ha cambiado, pero el runtime sí.
• El tunnel automático usa Cloudflare Argo Tunnel sin necesidad de cuenta propia de Cloudflare.
• shopify.app.toml es el archivo de configuración central de la app — reemplazó el modelo anterior basado en múltiples archivos .env. La mayoría de la configuración de la app vive ahí.
• El CLI soporta múltiples stores en paralelo: puedes trabajar en diferentes stores cambiando el flag --store sin re-autenticarte.

Sintaxis y anatomía

La estructura que genera el CLI para un theme (basado en Horizon):

brew-atlas-theme/
├── assets/
│   ├── base.css
│   └── theme.js
├── blocks/           # theme blocks (2025+) — reusables entre sections
├── config/
│   ├── settings_data.json
│   └── settings_schema.json
├── layout/
│   └── theme.liquid  # HTML raíz de todas las páginas
├── locales/
│   └── en.default.json
├── sections/
│   ├── header.liquid
│   ├── footer.liquid
│   └── pdp.liquid    # lo construimos en sección 05
├── snippets/
│   └── ...
└── templates/
    ├── product.json
    └── collection.json

La estructura de la app generada por el CLI:

brew-atlas-app/
├── app/
│   ├── routes/
│   │   ├── _index.tsx     # ruta raíz de la embedded app
│   │   └── app.tsx        # layout con App Bridge
│   └── shopify.server.ts  # configuración de autenticación OAuth
├── extensions/            # aquí van las extensiones (checkout, functions, etc.)
├── prisma/
│   └── schema.prisma      # DB para sesiones OAuth
├── shopify.app.toml       # configuración central de la app
└── package.json

Proyecto · Brew Atlas

Los READMEs están en brew-atlas/theme/README.md y brew-atlas/app/README.md. Léelos antes de ejecutar cualquier comando de CLI.

Errores comunes

Checklist senior

Quiz

Siguiente

Con el entorno configurado, la siguiente sección entra de lleno en Liquid: la sintaxis del lenguaje de templates que vive en todas las superficies del storefront. Si ya leíste Jinja, Handlebars o ERB, el salto es corto — pero hay detalles de scope y render que diferencian Liquid y que vale la pena entender antes de tocar un theme.