Com 10 anos de experiência em VTEX e dezenas de projetos entregues, identifiquei um padrão: a maioria dos problemas no go-live são previsíveis. Eles se repetem em projetos diferentes, independente do porte da loja ou da equipe envolvida.
1. Não usar workspace de desenvolvimento isolado
O workspace permite testar alterações sem impactar a loja em produção. O erro clássico é desenvolver direto no workspace master ou usar apenas um workspace compartilhado entre todos os devs. A boa prática é cada developer ter seu próprio workspace pessoal e um workspace de staging (ex: homolog) para testes integrados antes do merge.
2. Não fixar versões de apps e dependências
O manifest.json do VTEX IO usa semver para declarar dependências. Usar ranges como ^2.x pode resultar em atualizações automáticas que quebram funcionalidades em produção. Sempre fixe as versões de apps críticos (vtex.store, vtex.checkout-ui-custom) e revise changelogs antes de atualizar.
3. Ignorar a ordem de carregamento dos Pixel Apps
Pixel Apps de analytics (Google Tag Manager, Meta Pixel) são carregados de forma assíncrona, mas a ordem importa. Se um Pixel App depende de variáveis de outro (ex: dataLayer configurado pelo GTM), garantir a sequência correta evita eventos perdidos no início da sessão.
4. Não configurar corretamente o checkout
O Checkout VTEX tem customização própria via vtex.checkout-ui-custom. Um erro frequente é customizar o checkout via JavaScript injetado diretamente (orderForm customData), que pode ser sobrescrito por atualizações da plataforma. Use sempre o app de checkout para customizações sustentáveis.
5. Blocos órfãos no Store Theme
O Store Theme acumula blocos declarados mas nunca usados. Isso aumenta o bundle size e dificulta a manutenção. Faça auditorias periódicas, removendo blocos não referenciados e customizações de CSS sem propósito.
6. Cache de catálogo mal configurado
Preços e disponibilidade de estoque precisam de cache de curta duração. Já imagens de produto e descrições podem ter cache mais longo. Confundir as políticas de cache resulta em preços desatualizados ou performance degradada por cache muito curto em recursos estáticos.
7. Não testar em dispositivos móveis reais
Mais de 70% do tráfego de e-commerce no Brasil vem de dispositivos móveis. Testar apenas no Chrome DevTools com emulação mobile não é suficiente — comportamentos de gestos, teclado virtual e conexão 4G real podem revelar bugs invisíveis no emulador.
8. Implementar analytics sem validação de dados
Instalar o Pixel App do Google Analytics 4 e assumir que está funcionando é um erro comum. Sempre valide: os eventos de purchase no GA4 batem com os pedidos no painel VTEX? A receita está correta (sem frete duplicado, sem pedidos cancelados)? Use o DebugView do GA4 e compare números semana a semana.
9. Não configurar redirects na migração
Ao migrar de Legacy para IO, as URLs de produto e categoria frequentemente mudam. Sem redirects 301 configurados no VTEX Rewriter ou no Nginx, todo o SEO acumulado nas URLs antigas é perdido. Mapeie todos os redirects antes do go-live.
10. Não monitorar após o go-live
Configure alertas no Google Search Console para erros de crawl, monitore os Core Web Vitals no campo e acompanhe os relatórios de conversão no GA4 por pelo menos 30 dias após o lançamento. Muitos problemas só aparecem em produção com tráfego real.
Se você está planejando uma implementação VTEX IO e quer evitar esses erros, posso ajudar com uma consultoria de arquitetura ou auditoria da implementação atual.