Durante o desenvolvimento em VTEX IO, é comum realizar atualizações de versão major dos apps, especialmente do tema.
No entanto, esse processo pode trazer um problema sério: a perda de conteúdo configurado via Site Editor.
Felizmente, é possível evitar esse cenário. Neste post, você vai aprender como preservar o conteúdo existente mesmo após uma atualização de versão major do tema.
Por que o conteúdo pode ser perdido?
Antes de tudo, é importante entender o motivo do problema.
No VTEX IO, o conteúdo criado pelo Site Editor fica associado às IDs do tema.
Quando você altera a versão major de um app, essas IDs mudam.
Como consequência, o sistema passa a enxergar o tema como algo totalmente novo. Assim, o conteúdo anterior deixa de ser aplicado.
Por isso, se nenhuma ação for tomada, a perda de conteúdo pode acontecer.
Como preservar o conteúdo ao atualizar a versão major
Para resolver esse problema, o VTEX IO oferece uma solução via GraphQL.
Com ela, você consegue atualizar as IDs do tema, mantendo todo o conteúdo existente.
A seguir, veja o passo a passo.
Primeiramente, verifique se o GraphQL IDE está instalado no seu ambiente.
Caso ainda não esteja, execute o comando abaixo no terminal:
vtex install vtex.admin-graphql-ide@3.x
Depois disso, acesse o admin da loja e entre em:
/admin/graphql-ide
Passo 1: instalar o GraphQL IDE no admin
Primeiramente, verifique se o GraphQL IDE está instalado no seu ambiente.
Caso ainda não esteja, execute o comando abaixo no terminal:
vtex install vtex.admin-graphql-ide@3.x
Depois disso, acesse o admin da loja e entre em:
/admin/graphql-ide
Passo 2: acessar o app correto no GraphQL IDE
Dentro do GraphQL IDE, siga estes passos:
-
Abra o seletor “Escolher um aplicativo”
-
Selecione o app
vtex.pages-graphql@2.x
Esse app é responsável pelas operações relacionadas às páginas e temas.
Passo 3: executar a mutation de atualização de IDs
Agora, com o app correto selecionado, execute a mutation abaixo:
mutation {
updateThemeIds(
from: "{appvendor}.{appname}@{oldmajor}.x",
to: "{appvendor}.{appname}@{newmajor}.x"
)
}
O que essa mutation faz?
De forma simples, ela:
-
Mapeia as IDs do tema antigo
-
Atualiza essas IDs para a nova versão major
-
Mantém o vínculo com o conteúdo já cadastrado
Assim, o Site Editor continua exibindo os dados corretamente após a atualização.
Quando aplicar esse procedimento?
Sempre que você for:
-
Atualizar a versão major do tema
-
Subir uma nova major para produção
-
Migrar conteúdo entre versões incompatíveis
Nesse contexto, essa mutation se torna essencial.
Boas práticas para evitar problemas
Além disso, vale seguir algumas recomendações importantes:
-
Execute a mutation antes de validar o novo tema
-
Garanta que o vendor e o app name estejam corretos
-
Documente a mudança para o time
Dessa forma, você reduz riscos e evita retrabalho.
Conclusão
Atualizar a versão major do tema no VTEX IO não precisa significar perda de conteúdo.
Com o uso correto do GraphQL IDE e da mutation updateThemeIds, é possível manter toda a estrutura já criada no Site Editor.
Assim, você garante continuidade, consistência e mais segurança no processo de evolução do tema.
Quer se aprofundar em Front-end e VTEX IO?
Na DFreedom, trabalhamos com uma formação prática e orientada ao mercado. Por isso, nosso foco está no desenvolvimento web e no ecossistema da VTEX. Assim, atendemos desde quem está começando até profissionais em nível avançado.
