Plano de migração do Luma para o Hyvä: auditoria, fases e lançamento

Migrar uma loja Magento no ar do Luma, ou de um tema custom construído sobre o Luma, para o Hyvä é uma reconstrução do frontend, não um upgrade. O backend fica, mas todo template com JavaScript, todo arquivo LESS e toda extensão de frontend precisa de atenção. Os projetos que dão certo tratam isso como uma migração planejada, com auditoria, fases claras e um caminho de rollback. Este é o plano que sigo, na ordem em que sigo.

Fase 1: auditoria antes de estimar

Não estime uma migração para o Hyvä pela homepage. O custo está nos detalhes, e você só os encontra com uma auditoria. Eu levanto quatro listas.

Extensões com saída na storefront

Liste todo módulo habilitado que não seja core do Magento:

bin/magento module:status --enabled | grep -v '^Magento_' | grep -v '^PayPal_'

Para cada um, registre se ele adiciona algo à storefront (templates, JavaScript, CSS, componentes de checkout), quais páginas afeta e se o fornecedor entrega suporte a Hyvä. Módulos só de admin e de integração podem ser ignorados na estimativa de frontend. Este também é o momento de remover módulos que ninguém usa mais. Uma auditoria de extensões normalmente se paga aqui, porque cada módulo removido é uma tarefa de compatibilidade a menos.

Customizações do tema

Liste todo override de template, arquivo de layout, arquivo JavaScript, mixin e arquivo LESS no tema atual e nos módulos custom. Um jeito rápido de dimensionar:

find app/design/frontend -name '*.phtml' | wc -l
find app/design/frontend app/code -path '*view/frontend*' -name '*.js' | wc -l
find app/design/frontend app/code -path '*view/frontend*' -name 'requirejs-config.js'

A contagem de arquivos JavaScript e de mixins prevê o esforço melhor do que a contagem de templates. Cada mixin representa um comportamento que precisa ser entendido e reconstruído.

Checkout

Liste os métodos de pagamento, os métodos de envio com UI custom e toda customização do checkout (campos, steps, validações, autocomplete de endereço). O checkout é uma decisão própria, tratada na próxima fase.

Conteúdo

Descubra como o conteúdo é gerenciado: CMS pages e blocks, widgets, Page Builder, sliders de extensões. Conte os content types do Page Builder em uso e os CMS blocks com estilos ou scripts inline. O conteúdo que parecia bom no Luma vai precisar de novo estilo, e jQuery inline em CMS blocks vai parar de funcionar.

Fase 2: decisões

Com a auditoria pronta, tome três decisões de forma explícita e escreva-as.

1. Checkout. Lançar com fallback para o checkout Luma, ou com o Hyvä Checkout, ou outro checkout. Lançar o tema primeiro com o fallback e mover o checkout depois costuma ser menos arriscado. Os trade-offs estão na visão geral do Hyvä Checkout.
2. Cada extensão. Versão compatível do fornecedor, módulo compat da comunidade que já existe, o seu próprio módulo compat, fallback Luma para as rotas dela ou remoção. Veja módulos de compatibilidade do Hyvä para entender como cada opção funciona.
3. Escopo de design. Uma portabilidade fiel do design atual, ou um redesign. Combinar migração e redesign é comum, mas dobra o número de coisas que podem virar discussão. Se o design vai mudar, congele-o antes de o desenvolvimento começar.

Confira também o licenciamento do Hyvä e de qualquer produto relacionado que você pretenda usar. Os termos mudaram com o tempo, então leia os atuais em hyva.io em vez de confiar em artigos ou estimativas mais antigos.

Fase 3: fundação

• Instale o Hyvä e crie um child theme, como no guia de setup do tema Hyvä.
• Monte o build do Tailwind no CI para que o CSS compilado seja produzido antes do static content deploy.
• Configure primeiro, na config do Tailwind, as cores da marca, as fontes e os estilos base de componentes (botões, inputs, headings). Toda página construída depois se beneficia disso.
• Atribua o novo tema a uma store view só no staging. A produção continua com o Luma até o lançamento.

Como o tema é atribuído por store view na configuração de design, a mesma base de código pode servir o Luma em produção e o Hyvä no staging durante o projeto inteiro. Isso permite continuar entregando correções de backend em produção enquanto o frontend é reconstruído.

Fase 4: reconstrução página a página

Trabalhe na ordem em que os clientes veem o site e termine cada área antes de passar para a próxima.

1. Elementos globais: header, navegação, mini cart, caixa de busca, footer, aviso de cookies, mensagens. Aparecem em toda página e expõem cedo o tratamento das customer data sections.
2. Páginas de categoria: tiles de produto, navegação em camadas, ordenação, paginação, swatches.
3. Páginas de produto: todo tipo de produto que você vende. Produtos configuráveis com swatches e produtos bundle costumam levar mais tempo.
4. Página do carrinho e qualquer extensão do carrinho, como embalagem para presente ou cross sells.
5. Conta do cliente: login, cadastro, dashboard, pedidos, endereços, wishlist e páginas de extensões na área da conta.
6. CMS pages e conteúdo, incluindo os content types do Page Builder.
7. Checkout, conforme a decisão da fase 2.

Em cada área, refaça o comportamento custom com Alpine.js em vez de portar o jQuery linha por linha. Muito código de frontend do Luma existe para contornar a ordem de carregamento do RequireJS e os bindings do Knockout. Ele não precisa existir no Hyvä. Reaproveite as partes de backend: view models, blocks e controllers normalmente passam sem mudanças.

Fase 5: paridade de SEO e analytics

Uma reconstrução de frontend pode quebrar em silêncio coisas de que os buscadores e o marketing dependem. Antes do lançamento, compare o antigo e o novo em:

• URLs. Não devem mudar. Uma migração de tema não é a hora de mudar a estrutura de URLs.
• Title tags, meta descriptions, canonical tags, robots meta e hreflang em cada tipo de página.
• Dados estruturados de produtos, breadcrumbs e organização. Veja dados estruturados no Magento 2.
• Estrutura de headings e o texto visível nas páginas de categoria e de produto.
• Eventos de analytics e de tag manager: page views, view item, add to cart, begin checkout, purchase. Módulos de tracking baseados em Luma muitas vezes disparam eventos de código Knockout ou jQuery que não roda mais.

Faça um crawl das duas versões com o mesmo crawler e compare os resultados. É o jeito mais rápido de achar um canonical faltando ou um template quebrado em um tipo de página que ninguém testou à mão.

Fase 6: testes

• Testes funcionais de cada tipo de página em desktop e mobile, como visitante e logado.
• Finalização completa de pedido com todos os métodos de pagamento e todos os métodos de envio.
• Comportamento do full page cache: mini cart, nome do cliente, mensagens e preços por customer group em páginas cacheadas.
• Performance medida no staging com dados de produção, comparada com a linha de base do Luma que você registrou antes de começar.
• Noções básicas de acessibilidade: navegação por teclado em menus e modais, estados de foco, labels nos campos de formulário.

Fase 7: lançamento e rollback

O lançamento é uma mudança de configuração: atribuir o child theme do Hyvä às store views de produção, fazer o deploy do conteúdo estático e limpar os caches.

bin/magento setup:static-content:deploy -f --theme Acme/hyva --theme Magento/luma en_US
bin/magento cache:flush

Faça o deploy do conteúdo estático dos dois temas nas primeiras semanas. Se o fallback do checkout Luma está em uso, você precisa do tema Luma de qualquer forma. Se algo sério der errado depois do lançamento, o rollback é atribuir o tema antigo de volta à store view e limpar os caches. Mantenha o tema antigo na base de código e funcionando até ter confiança, e combine antes quem pode tomar essa decisão.

Lance no começo da semana, fora dos picos de venda, com desenvolvedores disponíveis. Acompanhe diariamente nas duas primeiras semanas os logs de erro, a taxa de conversão, a taxa de add to cart e a conclusão do checkout. Uma queda em um desses indicadores depois de uma mudança de frontend normalmente é uma interação quebrada em um tipo específico de página, e o analytics diz qual.

Depois do lançamento

• Remova os módulos que foram desabilitados durante a migração e não são mais necessários.
• Planeje a aposentadoria das rotas de fallback, se houver.
• Remova o tema antigo quando o rollback deixar de ser uma opção realista.
• Documente como o build do Tailwind, os módulos compat e a geração do hyva-themes.json se encaixam no deploy, para o próximo desenvolvedor não precisar redescobrir.

A migração também é um bom momento para definir um orçamento de performance. O Hyvä começa rápido, mas scripts de terceiros, imagens grandes e containers de tag manager podem levar uma loja de volta às velocidades do Luma em poucos meses. Acompanhe os Core Web Vitals pelos dados de campo depois do lançamento e trate regressões como bugs.

FAQ

Posso migrar para o Hyvä um tipo de página por vez em produção?

Não de forma limpa, porque o tema é atribuído por store view, não por página. A abordagem usual é construir a storefront inteira no staging e trocar a store view no lançamento, com fallback Luma só para rotas específicas como o checkout.

O que torna uma migração para o Hyvä cara?

Principalmente extensões de terceiros com JavaScript na storefront e comportamento custom do tema construído em jQuery ou Knockout. O número de templates importa menos do que a quantidade de JavaScript de frontend.

As URLs mudam ao migrar para o Hyvä?

Não deveriam. O Hyvä é um tema, então os URL rewrites continuam os mesmos. Confira canonical tags, dados estruturados e meta tags em cada tipo de página antes do lançamento.

Como faço rollback se o lançamento der errado?

Atribua o tema anterior de volta à store view na configuração de design, garanta que o conteúdo estático dele está deployado e limpe os caches. Mantenha o tema antigo na base de código até ter confiança.

Atendo como freelancer em migrações Magento e Hyvä. Se está planejando sair do Luma, fale comigo.