SEO na VTEX: o que configurar em cada versão da loja

SEO na VTEX é o trabalho de acertar os campos do Catálogo, que valem para qualquer loja da plataforma, e os ajustes que dependem da tecnologia da frente de loja. A VTEX tem três: o CMS Portal (Legado), o Store Framework, construído sobre o VTEX IO, e a FastStore. Na primeira, quase tudo se faz no Admin; nas outras duas, parte do trabalho passa por quem desenvolve a loja. Errar a versão leva a seguir um tutorial que não vale para você.

Os caminhos de menu citados aqui foram conferidos em 29 de outubro de 2026 na central de ajuda (help.vtex.com) e no portal de desenvolvedores da VTEX (developers.vtex.com). Quando a documentação não diz onde um ajuste fica, a gente avisa, em vez de adivinhar o menu.

Sua loja é legado, Store Framework ou FastStore?

O código-fonte responde em segundos. Abra a página inicial, aperte Ctrl+U e procure as marcas abaixo, as mesmas que usamos para classificar as lojas do teste deste texto:

O legado foi a primeira frente de loja da VTEX. A trilha de implementação da empresa avisa que ele não está mais disponível para quem chega agora, mas muita loja antiga segue nele. Há também lojas que usam a VTEX só por trás, com a vitrine feita em outra ferramenta: na busca por lojas para o teste, achamos duas com imagens servidas pela VTEX e código de outro frontend. Para elas, vale a parte do Catálogo; o resto depende da vitrine.

O que o Catálogo resolve nas três versões?

Título, descrição e endereço de produto, categoria e marca. O Catálogo é o mesmo módulo para qualquer frente de loja, então é o primeiro lugar a revisar:

O endereço do produto junta o domínio, o valor do campo que a ajuda chama de textLink e o sufixo /p. Um textLink chaleira-inox-2-litros vira sualoja.com.br/chaleira-inox-2-litros/p. Use hífen no lugar de espaço, nada de acento ou de sinais como _, ? e &, até 255 caracteres (a VTEX prefere 50) e nenhum dos termos admin, api, meta e a, que a plataforma reserva para outras funções. Esses termos também ficam proibidos no nome de categorias e marcas. URL deixada em branco é gerada pela VTEX.

Na FastStore, o Catálogo continua mandando, com uma ressalva. Quando falta título ou descrição no cadastro, a loja usa modelos que o desenvolvedor define no arquivo discovery.config.js (seo.plp.titleTemplate, seo.pdp.descriptionTemplate e os pares deles), com %s no lugar do nome. Na página de produto, a meta descrição do Catálogo só entra se a conta tiver ativa a flag do Intelligent Search; sem ela, aparece a descrição longa do produto ou o modelo. Pergunte ao time técnico qual é o seu caso.

Onde fica o título da página inicial em cada versão?

Em três lugares diferentes, um por versão, e é aqui que os tutoriais mais se confundem. No Store Framework, o campo fica nas configurações da loja; no legado, a ajuda nem mostra um campo de título para a home; na FastStore, ele mora no CMS, dentro da página Home:

• Store Framework: Configurações da loja > Storefront > Loja, aba Geral, com a Tag de título padrão, a Tag de descrição meta e a Metatag robots, que vem com index, follow. Depois de Aplicar, a mudança pode levar alguns minutos. Loja com vários bindings (por exemplo, um domínio por país) pode marcar Habilitar configuração por vínculo e escrever textos para cada um.
• CMS Portal (Legado): Configurações da loja > Storefront > Configurações, aba SEO, com palavras-chave e meta tag de descrição. A ajuda dessa tela não mostra campo de título para a página inicial.
• FastStore: Storefront > Headless CMS (Legacy), página Home, aba Settings, seção SEO. Lá estão Path, Default page title, Meta tag description, Canonical url for the page, Name e Publisher ID. Landing Pages têm campos parecidos.

O editor da FastStore está mudando. A VTEX anunciou que, a partir de 30 de março de 2026, migraria automaticamente as contas do Headless CMS (Legacy) para um novo VTEX CMS, mantendo o conteúdo, e em 13 de outubro divulgou esse CMS em acesso antecipado, no menu Storefront > Content. O tutorial de SEO da central ainda descreve a tela antiga; se o seu Admin já tem o menu novo, confira o resultado no código.

Na leitura que fizemos, uma das quatro lojas FastStore não tinha title, meta description nem canonical na página inicial, exatamente os campos da aba Settings da Home.

robots.txt e sitemap: o que a VTEX gera e onde se mexe?

O sitemap sai pronto em todas as versões, e o robots.txt tem uma caixa de texto no Admin do legado e do Store Framework. Na FastStore e nas lojas cross-border, a mudança passa por quem desenvolve a loja. Os detalhes de cada caso:

1. robots.txt no legado e no Store Framework: Configurações da loja > Storefront > Configurações, aba SEO, caixa Robots.txt. A própria ajuda se contradiz: a página de SEO do legado descreve essa caixa como se fosse a metatag robots (index, follow), e a página dedicada ao robots.txt trata a mesma caixa como o arquivo de regras. Vale a segunda: o texto dali vira o /robots.txt da loja.
2. Loja cross-border no Store Framework: usa um app de robots montado pelo desenvolvedor, com um arquivo por loja.
3. FastStore: a documentação de SEO que lemos não diz onde editar. Abra o seu /robots.txt e peça a mudança a quem publica a loja.
4. Sitemap: gerado sozinho em /sitemap.xml, dividido em departamentos, categorias, marcas e produtos. No Store Framework, o responsável é o app vtex.store-sitemap, com até 5 mil endereços por arquivo; página criada pelo desenvolvedor só entra com "isSitemapEntry": true na rota.
5. Sitemap na FastStore: usa o mesmo app, e a VTEX registra um problema conhecido, aberto em 13 de outubro de 2025 e ainda com status Backlog: as páginas criadas no CMS ficam fora do sitemap, e os endereços podem sair com o domínio seguro (o do checkout). Uma das lojas FastStore testadas declarava no robots.txt, ao lado do padrão, um segundo arquivo chamado hcms.xml.

Para enviar o arquivo ao Google, a ajuda da VTEX ainda mostra telas antigas do Search Console. Hoje basta abrir o relatório Sitemaps e digitar sitemap.xml em Adicionar um novo sitemap. O que o arquivo garante, e o que não garante, está no guia de sitemap do blog.

Onde se cadastra o redirecionamento 301 em cada versão?

Em telas diferentes, com regras próprias. Quando o textLink de um produto muda, o endereço antigo precisa de destino, e nenhuma página da ajuda que lemos diz que a plataforma cria esse redirecionamento por conta própria.

• Store Framework: Storefront > Redirecionamentos > Novo redirecionamento. Preencha De e Para sem o domínio (/chaleira-inox/p e /chaleira-inox-2-litros/p) e marque permanente; o temporário pede data final. Lotes entram por CSV separado por ponto e vírgula, e a ajuda alerta que o Google Planilhas exporta com vírgula. Parâmetros depois do ? não são repassados, rotas como /, login e conta não aceitam redirecionamento, e o usuário precisa do recurso CMS Settings no perfil.
• CMS Portal (Legado): Storefront > Layout, pastas CMS e URL Builder, botão Add. Todo mapeamento dali é 301, com Url from e Url to sem domínio e Start date obrigatório. Deixe End date vazio numa mudança definitiva, porque o mapeamento deixa de valer na data final. Lotes entram por planilha Excel 97-2003 (.xls).
• FastStore: o redirecionamento fica no projeto, pelo guia de rotas da FastStore. Com mais de 1.024 regras, a flag beta enableRedirects libera a tela de Redirecionamentos do Admin.

Teste também o domínio. As 10 lojas que lemos levavam http:// para https:// com 301. A variante com ou sem www, conferida em 9 delas (a décima roda num subdomínio), teve quatro comportamentos: 5 redirecionavam direto com 301, 2 passavam antes por http://, ganhando um salto a mais, 1 usava 302 (temporário) e 1 nem respondia. Para produto que saiu de linha, veja quando o 301 resolve e quando a página deve responder 404.

O canonical da VTEX dá conta de busca e filtros?

Na maior parte das páginas, sim; nos filtros, nem sempre. O guia de SEO para desenvolvedores diz que a VTEX gera o canonical sozinha em produto, categoria, marca e páginas personalizadas, e que lojas cross-border precisam configurá-lo para cada binding.

O ponto fraco são as URLs com o parâmetro map, que diz à busca o que cada trecho do endereço significa. Um problema conhecido aberto em 2017, ainda em Backlog, descreve o efeito: em /feminino/tenis/corrida?map=c,c,specificationFilter_7, o canonical corta tudo depois do ?, e a página filtrada declara como oficial um endereço que pode mostrar outros produtos. A VTEX diz que não há paliativo.

Se a combinação merece aparecer no Google, dê a ela um endereço próprio. No Store Framework, isso se faz em Storefront > Páginas > Criar página, com Título, URL e Descrição; a ajuda avisa que a URL de uma rota existente não pode ser alterada depois. No legado, o caminho é uma pasta do CMS com o campo Search Context (Default), que carrega a busca filtrada num endereço sem filtros. Se não merece, tire-a do rastreamento, como explica o texto sobre filtros e parâmetros que gastam as visitas do robô.

Dois ajustes do Store Framework ajudam o robô a percorrer a listagem:

• Em Storefront > Site Editor, em cada página de lista de produtos, abra o bloco Resultado de busca flexível, clique em Mostrar mais e escolha, em Comportamento do botão, "Link para a página - Melhora o SEO, pode mudar a aparência do botão". Repita em Mostrar anteriores.
• No tema, o bloco filter-navigator.v3 monta os filtros de categoria como div com papel de link. Com categoryFiltersMode em href, eles viram links de verdade. É mudança de código.

No teste apareceram tropeços de configuração, não da plataforma: uma página inicial FastStore com o canonical escrito sem https:// (o navegador entende aquilo como caminho relativo, e o endereço resultante não existe) e, na mesma loja, canonical relativo na categoria. Como escrever a tag do jeito que o Google aceita está no texto sobre a versão oficial de cada página.

Que dados estruturados cada versão entrega?

Aqui a versão pesa mais do que o lojista. No teste, as lojas legadas não tinham nenhum JSON-LD, as quatro em Store Framework traziam o bloco de produto e as FastStore variavam de uma loja para outra. Os números:

O Google também lê microdados, mas mudá-los exige editar o template, e nenhuma das lojas legadas declarava a empresa nem o nome do site. No Store Framework, o bloco de produto trazia preço, marca, SKU e, em três das quatro lojas, GTIN. Na FastStore, uma loja tinha só a trilha, sem o produto.

Para a FastStore, o guia da VTEX lista o que revisar no schema de produto: GTIN ou UPC, o título de SEO no campo name, disponibilidade com os endereços do schema.org (InStock, OutOfStock), código do fabricante (MPN) e a retirada dos campos antigos listPriceWithTaxes e priceWithTaxes. A página da central sobre dados estruturados, atualizada pela última vez em 2019, ainda indica o Marcador de Dados do Search Console. Prefira JSON-LD no código e confira o resultado na nossa ferramenta que lê o JSON-LD da página.

O que chega ao robô antes de qualquer JavaScript?

É o que a documentação quase não trata e o que mais separou as lojas. Na nossa leitura, o legado entregou o HTML completo, o Store Framework entregou páginas grandes demais para o limite do Googlebot e a FastStore concentrou os casos de página vazia.

Em 29 de outubro de 2026, lemos 10 lojas VTEX brasileiras em funcionamento: 2 no CMS Portal, 4 no Store Framework e 4 na FastStore, classificadas pelas marcas da primeira tabela. Pedimos de cada uma o robots.txt, a página inicial, uma categoria e um produto, mais as variantes de domínio e o sitemap. Um pedido por vez, com pelo menos 2 segundos entre eles, o user-agent do Nota do Site, no máximo 2 MB lidos por resposta e nenhum script executado. Uma loja FastStore respondeu 429 (excesso de pedidos) à categoria, então as categorias somam 9. Dez lojas mostram o que pode acontecer, não a média da plataforma. A base de 53 sites .br do validador, colhida de 20 a 22/10, tinha só 5 lojas VTEX, o que não dá taxa nenhuma; daí este teste.

O que deu certo: as 10 páginas de produto traziam title, meta description e canonical apontando para si mesmas, e os 10 robots.txt respondiam, declaravam o sitemap e não barravam o Googlebot nem robôs de IA. Cinco liberavam robôs de IA pelo nome.

O que deu errado, por versão:

• Store Framework, páginas pesadas. Em 9 das 12 páginas (75%), o HTML passou de 2 MB depois de descompactado; a maior tinha quase 6 MB. A documentação do Google diz que "o Googlebot rastreia os primeiros 2 MB de um tipo de arquivo compatível", medidos sem compactação, e que só a parte baixada segue para indexação. Nas páginas medidas, title, canonical, H1 e JSON-LD vinham nos primeiros 0,7 MB, e o excesso era o bloco __STATE__, que o JavaScript usa para montar a tela. Mesmo assim, uma categoria chegou duas vezes sem title, sem canonical e sem texto.
• Store Framework, preço fora do texto. Num produto, o preço só existia no JSON-LD.
• FastStore, produto vazio. Uma página tinha title, descrição, canonical e o bloco Product, mas o corpo era feito de caixas reservadas para seções que o JavaScript preenche depois: zero palavras, sem nome nem preço. O guia de SEO da VTEX pede para evitar o carregamento sob demanda no conteúdo principal de listagens e produtos.
• Listagens sem link. Em 3 das 9 categorias (uma Store Framework e duas FastStore), nenhum link de produto aparecia no HTML. O Google executa o JavaScript e ainda tem o sitemap; um robô de IA que não executa script não vê nada, o mesmo efeito do teste dos sites que chegam vazios a quem não roda JavaScript.
• Legado, templates antigos. O HTML vinha completo, com nome, preço e o bloco de descrição no texto. Os tropeços eram de template: três H1 na página de produto das duas lojas, dois deles com o nome da loja, e uma categoria com dois <title>, um com código numérico, e a mesma meta description da página inicial.

Como conferir sua loja VTEX em dez minutos?

Com quatro endereços da loja abertos numa janela anônima e o código-fonte à vista. Cada passo mostra se o ajuste feito no Admin chegou à página publicada e se o texto depende de JavaScript:

1. Produto: localize <title, name="description", rel="canonical" e application/ld+json. Depois busque o preço e uma frase da descrição. Se só aparecem dentro de <script>, dependem de JavaScript.
2. Categoria: busque /p". Nenhum resultado quer dizer que os links dos produtos não estão no HTML.
3. Página inicial: o title deve ser o que você configurou, e não um vazio ou genérico.
4. Domínio: digite a outra forma do endereço (com ou sem www) e a versão http://. As duas devem cair no endereço principal num salto só.
5. Search Console: no Store Framework, instale o app Google Search Console pela Loja de aplicativos e cole no campo Content só o código de dentro do content= da meta tag. No legado, a meta tag vai no <head> do template Home, em Storefront > Layout, pastas CMS e HTML Templates. A ajuda não cobre a FastStore; nela, a propriedade de domínio, verificada pelo DNS, não depende do código da loja.

Se preferir uma leitura só, a análise do Nota do Site, que lê a loja como um robô, faz isso sem executar JavaScript e, ao reconhecer a VTEX, mostra nas regras que se corrigem pelo Admin o caminho da tela e o link da ajuda oficial. Com conta, você analisa de novo depois da correção e compara as duas análises.

O que pedir à agência ou ao time que cuida da loja?

Três respostas. A primeira é a versão da frente de loja e se há plano de migrar, porque isso decide quem mexe no título da página inicial e no robots.txt. A segunda: categorias e produtos entregam nome, preço e links no HTML ou só depois do JavaScript? Peça o teste do código-fonte da seção anterior, e não um print do navegador. A terceira: quem cadastra o 301 quando um textLink muda, e em qual tela. Antes da reunião, faça você mesmo o teste no produto que mais vende: em dois minutos, ele mostra o que o Google e os robôs de IA recebem da sua loja.