VTEX Audit 🚀

CLI profissional para auditoria de Performance, SEO e Qualidade Técnica em lojas VTEX IO, baseado no Lighthouse — com diagnóstico acionável, foco em LCP, 3rd‑party scripts e boas práticas reais de e‑commerce.

Não é apenas um wrapper do Lighthouse.
É um auditor especializado em VTEX IO.

✨ Principais diferenciais

✅ Auditoria opiniada para VTEX IO
✅ Identificação automática do Largest Contentful Paint (LCP)
✅ Descoberta do elemento exato responsável pelo LCP
✅ Ranking dos arquivos mais pesados
✅ Ranking das requisições mais lentas
✅ Detecção de scripts third‑party
✅ Sugestões automáticas de correções prováveis
✅ Relatórios JSON e HTML
✅ Interface de terminal profissional
✅ Pronto para CI/CD e pipelines

📦 Instalação

Uso rápido (recomendado)

npx vtex-audit --url https://www.sualoja.com.br

Instalação global

npm install -g vtex-audit

🚀 Uso

Mobile (default)

vtex-audit --url https://www.sualoja.com.br

Desktop

vtex-audit --url https://www.sualoja.com.br --device desktop

Gerar relatórios

vtex-audit --url https://www.sualoja.com.br --json --html

Diretório de saída

vtex-audit --url https://www.sualoja.com.br --out ./audit

📊 Exemplo de saída

VTEX Audit (mobile)
URL: https://www.loja.com.br

Scores (Lighthouse)
Performance: 51
SEO: 100
Accessibility: 91
Best Practices: 57

Core metrics
LCP: 16.7s
CLS: 0.004
TBT: 375ms
Requests: 168
Total weight: 2.4 MB

LCP details
Element: img.banner__img
Asset: https://.../banner-home.webp

Top culprits
Largest transfers:
- hero-banner.webp (420 KB)
- vendor.js (310 KB)

Slowest requests:
- google-analytics.js (1.8s)
- facebook-pixel.js (1.4s)

Top domains:
- loja.vtexassets.com
- www.googletagmanager.com ⚠️
- connect.facebook.net ⚠️

Likely fixes
→ Priorizar banner LCP
→ Converter imagens para WebP / AVIF
→ Adiar scripts third‑party
→ Reduzir apps globais VTEX

🔍 O que o VTEX Audit analisa

Lighthouse

• Performance
• SEO
• Accessibility
• Best Practices

Métricas principais

• Largest Contentful Paint (LCP)
• Cumulative Layout Shift (CLS)
• Total Blocking Time (TBT)
• Time To Interactive (TTI)
• Speed Index

🔎 SEO custom (fora do Lighthouse)

• ❌ Página sem <h1>
• ❌ Imagens sem atributo alt
• ❌ Meta title ausente
• ❌ Meta description ausente
• ❌ Conteúdo vazio acima da dobra

⚡ Performance avançada

• Identificação do elemento real do LCP
• URL do asset responsável
• Top 10 arquivos por peso
• Top 10 requests mais lentas
• Ranking por domínio
• Destaque automático de third‑party scripts
• Diagnóstico focado em VTEX IO

🧠 Diferença para o Lighthouse tradicional

| Lighthouse | VTEX Audit | |----------|-----------| | Genérico | Especializado em VTEX | | Interface web | CLI profissional | | Apenas notas | Diagnóstico acionável | | Sem ranking | Top culpados | | Sem noção de apps | Identifica third‑party | | Manual | Automatizável | | Sem contexto | Sugestões práticas |

🤖 CI / GitHub Actions

- name: VTEX Audit
  run: npx vtex-audit --url https://www.sualoja.com.br

Ideal para validar performance antes de deploy.

📁 Estrutura dos relatórios

./vtex-audit
├── mobile-home.json
├── mobile-home.html
├── seo-report.json

🛠 Stack

• Node.js 18+
• TypeScript
• Lighthouse
• Chrome Launcher
• Ora
• Boxen
• CLI Table
• Pretty Bytes

🧭 Roadmap

• [ ] Auditoria por múltiplas rotas (Home, PLP, PDP)
• [ ] Comparação entre deploys
• [ ] Exportação Markdown
• [ ] Dashboard Web
• [ ] Integração com VTEX Admin
• [ ] GitHub Checks
• [ ] VTEX Toolbelt Plugin

👨‍💻 Autor

Denis Palhares Gonçalves
Senior Full Stack Developer
Especialista em VTEX IO
+10 anos em e‑commerce

📄 Licença

MIT