Como crear apps VTEX IO: guia practica para desarrolladores
Las apps VTEX IO son la forma oficial de extender la plataforma VTEX. Desde componentes visuales de storefront hasta backends con APIs personalizadas, el sistema de apps permite crear funcionalidades que el ecosistema estandar no cubre. Esta guia cubre todo el proceso: desde el setup inicial hasta el deploy en produccion, con foco en buenas practicas de TypeScript, performance y mantenimiento.
Setup del ambiente de desarrollo
El primer paso es instalar la VTEX CLI globalmente via npm: npm install -g vtex. Luego, autenticarse con vtex login tu-cuenta. Crear un workspace de desarrollo con vtex use nombre-workspace. El workspace aisla tus cambios del ambiente de produccion. Verifica la version de Node.js (recomendado 18+) e instala Yarn como gestor de paquetes. Para crear una nueva app, usa vtex init y selecciona el template adecuado (react, node, service o graphql). El template genera la estructura base con manifest.json, directorio del builder y configuraciones iniciales. A partir de ahi, vtex link conecta tu codigo local al workspace con hot reload.
Estructura de una app VTEX IO
Toda app VTEX IO tiene un manifest.json en la raiz. Este archivo define: vendor (cuenta propietaria), name (identificador unico), version (semver), builders (cuales builders usa la app), dependencies (apps que esta app consume), policies (permisos de acceso a APIs y servicios). Los builders determinan la estructura de directorios. Una app con builder react tendra un directorio react/ con componentes TypeScript/React. Una app con builder node tendra node/ con middleware y servicios. Una app con builder graphql tendra graphql/ con schemas y resolvers. Una app puede combinar multiples builders.
Builder React: componentes de storefront
El builder react permite crear componentes que aparecen en la tienda. El componente es un React function component exportado como default. El archivo store/interfaces.json declara el bloque para Store Framework: nombre del bloque, componente que renderiza y schema de propiedades. Las props se definen via JSON Schema y aparecen en el Site Editor (admin visual). Para estilizacion, usa CSS Modules o la API de CSS Handles para permitir personalizacion externa. Evita inline styles y estilos globales. Usa TypeScript estricto: define interfaces para props, evita any y valida datos de APIs con type guards.
Builder Node: backend y servicios
El builder node crea backends Express-like que corren en el runtime VTEX IO. El entry point es node/index.ts que exporta un objeto Service con routes y handlers. Cada handler recibe ctx (context) con metodos para acceder APIs internas de VTEX (catalog, checkout, OMS), hacer llamadas externas y manipular cache. Casos de uso comunes: middleware de integracion, procesamiento de webhooks, tareas programadas y endpoints personalizados para el frontend. Usa TypeScript para todo el backend. Define interfaces para payloads. Trata errores con try/catch y retorna status codes semanticos.
Builder GraphQL: APIs tipadas
El builder graphql expone APIs GraphQL para la tienda. El archivo graphql/schema.graphql define types, queries y mutations. Los resolvers en graphql/resolvers/ implementan la logica. Las queries son consumidas por el frontend via hooks useQuery de react-apollo. GraphQL de VTEX IO soporta directivas de cache (@cacheControl) que determinan cuanto tiempo la respuesta queda en cache. Usa maxAge y scope para controlar invalidacion. Para queries de datos que cambian raramente, configura cache largo. Para queries dependientes del usuario (carrito, wishlist), usa scope PRIVATE sin cache.
Tests y calidad
Apps VTEX IO soportan tests unitarios con Jest. Configura jest.config.js en el directorio del builder. Para componentes React, usa React Testing Library. Para el backend Node, testa handlers aisladamente mockeando ctx. Valida la app manualmente en el workspace antes de publicar. Verifica performance con Lighthouse antes y despues de instalar la app. Cada app agrega peso al bundle. Usa ESLint con reglas TypeScript estrictas. Configura lint como step del CI para garantizar calidad.
Deploy y publicacion
El ciclo de publicacion sigue: desarrollo local con vtex link, test en workspace con vtex deploy, publicacion en registro con vtex publish. Despues de publicar, la app queda disponible via vtex install vendor.app-name@version. Para apps internas, vtex deploy en el workspace de produccion (master) es suficiente. Para apps distribuidas, vtex publish registra la version. Versionado sigue semver: patch para fixes, minor para features retrocompatibles, major para breaking changes. Usa vtex release para automatizar bump de version, tag git y publicacion.
Buenas practicas y errores comunes
Manten apps pequenas y enfocadas. Declara solo las policies necesarias: principio de menor privilegio. No hagas fetch en cascada en el backend: usa Promise.all para llamadas paralelas. No almacenes secretos en el codigo: usa VTEX Settings o variables de ambiente del workspace. Evita queries GraphQL N+1: busca datos en lote. No ignores errores de TypeScript con ts-ignore: corrige el tipo. Monitorea el tiempo de respuesta de tus rutas. Y lo mas importante: antes de crear una app, verifica si el problema ya tiene solucion en el marketplace.