Como criar apps VTEX IO: guia pratico para desenvolvedores
Apps VTEX IO sao a forma oficial de estender a plataforma VTEX. Desde componentes visuais de storefront ate backends com APIs customizadas, o sistema de apps permite criar funcionalidades que o ecossistema padrao nao cobre. Este guia cobre todo o processo: do setup inicial ate o deploy em producao, com foco em boas praticas de TypeScript, performance e manutencao.
Setup do ambiente de desenvolvimento
O primeiro passo e instalar a VTEX CLI globalmente via npm: npm install -g vtex. Depois, autentique-se com vtex login sua-conta. Crie um workspace de desenvolvimento com vtex use nome-do-workspace. O workspace isola suas mudancas do ambiente de producao. Verifique a versao do Node.js (recomendado 18+) e instale o Yarn como gerenciador de pacotes. Para criar uma nova app, use vtex init e selecione o template adequado (react, node, service, ou graphql). O template gera a estrutura base com manifest.json, diretorio do builder e configuracoes iniciais. A partir dai, vtex link conecta seu codigo local ao workspace com hot reload.
Estrutura de uma app VTEX IO
Toda app VTEX IO tem um manifest.json na raiz. Esse arquivo define: vendor (conta proprietaria), name (identificador unico), version (semver), builders (quais builders a app usa), dependencies (apps que esta app consome), policies (permissoes de acesso a APIs e servicos). Os builders determinam a estrutura de diretorios. Uma app com builder react tera um diretorio react/ com componentes TypeScript/React. Uma app com builder node tera node/ com middleware e servicos. Uma app com builder graphql tera graphql/ com schemas e resolvers. Uma app pode combinar multiplos builders. Exemplo: uma app de reviews pode ter react/ para o componente visual, node/ para o backend que persiste dados e graphql/ para a API que conecta os dois.
Builder React: componentes de storefront
O builder react permite criar componentes que aparecem na loja. O componente e um React function component exportado como default. O arquivo store/interfaces.json declara o bloco para o Store Framework: nome do bloco, componente que ele renderiza e schema de propriedades. As props sao definidas via JSON Schema e aparecem no Site Editor (admin visual). Para estilizacao, use CSS Modules ou a API de CSS Handles para permitir customizacao externa. Evite inline styles e estilos globais. Use TypeScript estrito: defina interfaces para props, evite any e valide dados de APIs com type guards. Cada componente deve ser focado: um bloco, uma responsabilidade. Componentes grandes devem ser divididos em sub-componentes internos.
Builder Node: backend e servicos
O builder node cria backends Express-like que rodam no runtime VTEX IO. O entry point e node/index.ts que exporta um objeto Service com routes e handlers. Cada handler recebe ctx (context) com metodos para acessar APIs internas da VTEX (catalog, checkout, OMS), fazer chamadas externas e manipular cache. Casos de uso comuns: middleware de integracao com APIs externas, processamento de webhooks, tarefas agendadas (schedulers) e endpoints customizados para o frontend. Use TypeScript para todo o backend. Defina interfaces para payloads de entrada e saida. Trate erros com try/catch e retorne status codes semanticos. Configure cache adequadamente: rotas que nao mudam frequentemente devem ter cache agressivo para reduzir latencia.
Builder GraphQL: APIs tipadas
O builder graphql expoe APIs GraphQL para a loja. O arquivo graphql/schema.graphql define types, queries e mutations. Os resolvers em graphql/resolvers/ implementam a logica. Queries sao consumidas pelo frontend via hooks useQuery do react-apollo. O GraphQL da VTEX IO suporta diretivas de cache (@cacheControl) que determinam por quanto tempo a resposta fica em cache. Use maxAge e scope para controlar invalidacao. Para queries que buscam dados que mudam raramente (configuracoes, listas estaticas), configure cache longo. Para queries que dependem do usuario (carrinho, wishlist), use scope PRIVATE sem cache.
Testes e qualidade
Apps VTEX IO suportam testes unitarios com Jest. Configure jest.config.js no diretorio do builder (react/jest.config.js ou node/jest.config.js). Para componentes React, use React Testing Library. Para o backend Node, teste handlers isoladamente mockando o ctx. Alem de testes unitarios, valide a app manualmente no workspace antes de publicar. Use vtex link e navegue pela loja testando todos os cenarios. Verifique performance com Lighthouse antes e depois de instalar a app. Cada app adiciona peso ao bundle; monitore o impacto. Use ESLint com regras TypeScript strict. Configure o lint como step do CI para garantir qualidade em todo commit.
Deploy e publicacao
O ciclo de publicacao segue: desenvolvimento local com vtex link, teste no workspace com vtex deploy, publicacao no registro com vtex publish. Apos publicar, a app fica disponivel para instalacao via vtex install vendor.app-name@version. Para apps internas (nao publicadas no marketplace), vtex deploy no workspace de producao (master) e suficiente. Para apps distribuidas, vtex publish registra a versao e a torna acessivel para outras contas. Versionamento segue semver: patch para fixes, minor para features retrocompativeis, major para breaking changes. Mantenha um CHANGELOG e documente breaking changes claramente. Use vtex release para automatizar bump de versao, tag git e publicacao em um comando.
Boas praticas e erros comuns
Mantenha apps pequenas e focadas. Uma app que faz tudo vira um monolito dificil de manter. Declare apenas as policies necessarias no manifest.json: principio do menor privilegio. Nao faca fetch em cascata (waterfall requests) no backend: use Promise.all para chamadas paralelas. Nao armazene segredos no codigo: use o VTEX Settings ou variáveis de ambiente do workspace. Evite GraphQL queries N+1: busque dados em lote quando possivel. Nao ignore erros de TypeScript com ts-ignore: corrija o tipo. Monitore o tempo de resposta das suas rotas: endpoints lentos degradam a experiencia do usuario. E o mais importante: antes de criar uma app, verifique se o problema ja tem solucao no marketplace.