VTEX IO headless: duas fontes de verdade e o custo real

A loja headless não falha no front end. Falha quando aparência e conteúdo moram em bases diferentes. A vitrine é uma coisa, o esquema de conteúdo é outra. Quem mantém os dois separados paga em retrabalho sempre que uma campanha pede uma seção que o design system nunca previu.

O que muda de verdade quando a loja fica headless

A VTEX descreve comércio headless (em inglês) como o uso das funções centrais de comércio por APIs REST, com a vitrine construída fora das soluções de storefront da própria plataforma. A mesma página declara que a VTEX não oferece autenticação headless para o comprador, então a página de login continua nativa e a interface redireciona a pessoa para /login.

Em resumo, a mudança é esta. Catálogo, preço, estoque, promoção e pedido continuam rodando no núcleo de comércio. O que sai é a camada que montava a página.

O FastStore (em inglês) é o kit que a VTEX mantém para essa camada: um projeto Jamstack com um pacote Core, um SDK, um pacote de UI e um pacote de API. É no pacote de UI que o design system vive, montado sobre componentes FastStore e estilizado com Sass.

Ou seja, a mudança não é a loja virar código. A mudança é a composição da página deixar de ser configuração dentro da plataforma e virar um artefato que o time constrói, revisa e publica.

Conteúdo editorial não é dado de catálogo

Dois tipos de dado circulam numa vitrine headless, e cada um obedece a uma regra própria.

Dado de catálogo é fato sobre o produto: nome, preço, estoque, imagem, variação, categoria. Tem um dono, o núcleo de comércio, e muda por operação de catálogo.

Conteúdo editorial é decisão sobre a página: qual banner abre a home, a ordem das prateleiras, o texto de uma landing page, o selo da campanha. Não tem dono no catálogo porque não descreve o produto.

O CMS da VTEX (em inglês) documenta tipos de conteúdo como home, pdp, plp e landingPage, com componentes declarados em JSON Schema. Um componente é um grupo de campos (em inglês). Seção é o componente que funciona como contêiner, e é a unidade que o editor arrasta e reordena.

Uma seção pode apontar para uma coleção, e é aí que a confusão nasce. A prateleira é editorial. Os produtos dentro dela são catálogo. Quando o time de campanha edita a prateleira e o time de catálogo edita a coleção, os dois acham que mudaram a página.

O retrabalho nasce dessa mistura. O problema não é o volume de conteúdo, é não saber quem é dono de cada campo. A taxonomia do NN/g (em inglês) separa quatro modelos de organização: a navegação, a estrutura de arquitetura da informação, a taxonomia e o modelo de conteúdo. A prateleira pertence ao modelo de conteúdo, e o filtro que a mesma palavra nomeia pertence à taxonomia.

Por que duas fontes de verdade geram retrabalho

Um campo só existe para quem lê se três coisas concordarem: o design system renderiza, o esquema de conteúdo declara e o runtime faz o mapeamento.

O guia da VTEX sobre componentes e seções (em inglês) afirma que a vitrine faz um mapeamento em tempo de execução. A hierarquia de tipos de conteúdo, seções e componentes vira componente de interface e HTML de verdade. Esse mapeamento é código.

Quando o esquema mora numa base e o design system mora em outra, o mapeamento é refeito na mão a cada campanha. O editor vê um campo que a vitrine não renderiza, ou a vitrine entrega uma seção que nenhum editor consegue preencher.

O plugin de conteúdo (em inglês) deixa a direção explícita. O comando generate-schema junta esquemas de componentes, tipos de conteúdo e o esquema base do FastStore num arquivo só, e o upload-schema envia esse arquivo para o Schema Registry. O esquema é artefato do projeto, versionado junto com o código.

Manter os dois na mesma base torna o mapeamento revisável, e isso pesa mais que preferência de ferramenta. O NN/g trata padrões de conteúdo como parte do design system (em inglês), com os mesmos papéis, responsabilidades e revisão periódica que os componentes de interface.

O que quebra a cada campanha

Três falhas aparecem sempre, e todas vêm dessa separação.

O componente que só existe na vitrine. Alguém monta um hero de lançamento direto no front end, fora do tipo de conteúdo. No dia, funciona. Na campanha seguinte o CMS não oferece esse hero, e o trabalho é refeito.

O campo que só o marketing usa. Selo de campanha, etiqueta, contagem regressiva. Se o campo não está no esquema, ele vive num valor fixo no código ou numa planilha que alguém cola na mão. Se está no esquema mas nenhum token do design system cobre, ele renderiza com o peso errado.

A promoção que o catálogo não conhece. Preço e promoção vivem no núcleo de comércio, não no CMS. Uma página que mostra um número digitado pelo editor cria uma segunda fonte de verdade para preço, e o checkout vai discordar.

A documentação do CMS legado (em inglês) acrescenta uma quarta armadilha: os escopos. Um tipo de conteúdo com escopo pdp só pode ser usado em página de produto. O editor que quer um bloco de campanha na busca descobre que o tipo não aparece, e o chamado vai para o time de front end.

O NN/g lista o mesmo problema pelo lado da estrutura (em inglês), em sites que tratam cada item como unidade isolada e não oferecem caminho para o que é relacionado.

Quando a loja não deve ser headless

Headless é uma camada de engenharia que você vai manter para sempre. É a resposta errada em três casos comuns.

Catálogo pequeno. Quando algumas dezenas de produtos cobrem a oferta, a vitrine padrão já resolve busca, página de produto e checkout. O projeto headless compra um pipeline de build para resolver um problema que a loja não tem.

Time sem dono do front end. Headless exige alguém responsável por build, deploy, dependências e orçamento de performance depois do lançamento. Sem essa pessoa, a loja fica com o custo e perde o ganho.

Operação que muda pouco. Poucas campanhas por ano e pouca variação editorial não justificam uma camada nova de composição. Uma customização de tema resolve com menos superfície.

Existe ainda um limite técnico que precisa ser conhecido antes da decisão. A VTEX declara que não oferece autenticação headless para o comprador (em inglês), então a página de login continua nativa. Se a marca exige uma tela de login desenhada do zero, a plataforma não entrega isso hoje.

O que medir para saber se a arquitetura funciona

Seis números dizem se o projeto se pagou. Todos saem da própria loja, não do fornecedor.

Seções declaradas contra seções usadas. Conte as seções e os tipos de conteúdo do esquema, depois os que aparecem em páginas publicadas. Seção que ninguém usa é peso no repositório e opção desperdiçada na lista do editor.

Tempo do briefing até a página no ar. Meça o mesmo time antes e depois, no mesmo tipo de campanha. É o número que o projeto existe para mover.

Chamados por campanha que precisam de desenvolvedor. Se a contagem continua igual, o projeto pagou o custo e manteve o problema.

Páginas cujo conteúdo mudou sem deploy. Esse é o ponto do CMS desacoplado, e a resposta é binária. Ou acontece, ou o CMS é formalidade.

Conflitos de preço achados depois da campanha no ar. O número esperado é zero. Qualquer ocorrência significa uma segunda fonte de verdade para preço.

Core Web Vitals no percentil 75: LCP até 2,5 segundos, INP até 200 milissegundos, CLS até 0,1. O FastStore declara que busca alta pontuação em testes como Lighthouse e Web Vitals, então a métrica faz parte da promessa.

Onde as fontes divergem

Os artigos do NN/g não descrevem a mesma manutenção, e a diferença muda o orçamento.

Padrões de conteúdo no design system (em inglês) trata conteúdo como parte do sistema, com manutenção anual. Taxonomia 101 (em inglês) coloca o vocabulário controlado numa camada separada, mantida por quem governa o vocabulário e não por quem escreve a página.

Web Vitals define a aprovação no percentil 75, medida no campo. Os três concordam que manter a qualidade exige alguém responsável, com nome.