Guia de setup do tema Hyvä no Magento 2.4.8: da instalação ao deploy

Configurar o Hyvä em uma loja Magento 2.4.8 não é difícil, mas a ordem dos passos importa e alguns detalhes pegam as pessoas no primeiro projeto: onde fica o build do Tailwind, por que os estilos parecem quebrados depois de um deploy e como lidar com módulos que ainda esperam o Luma. Este guia percorre um setup limpo em ambiente de desenvolvimento, do Composer até um child theme funcionando com seu próprio build de CSS.

Se você ainda está decidindo se o Hyvä é o caminho certo, leia antes Hyvä vs Luma para desenvolvedores. Este artigo parte do princípio de que a decisão já foi tomada.

O que você precisa antes de começar

• Magento Open Source ou Adobe Commerce 2.4.x. Confira na documentação do Hyvä as versões exatas suportadas pela release do Hyvä que você pretende instalar.
• PHP 8.3 ou 8.4 para o Magento 2.4.8.
• Node.js e npm na máquina que faz o build do CSS. É o seu ambiente local e o seu CI ou servidor de build, não necessariamente a produção.
• Acesso aos pacotes do Hyvä. Como se obtém o acesso, e quanto custa, mudou com o tempo. Veja em hyva.io os termos atuais de licenciamento e instalação antes de orçar o projeto.

Faça a primeira instalação em uma cópia local. Um setup baseado em Docker, como Warden ou DDEV, facilita voltar atrás se algo der errado. Veja ambientes locais de Magento com Docker e Warden se precisar de um.

Instalando os pacotes com Composer

A documentação do Hyvä dá a configuração de repositório que corresponde ao seu tipo de acesso. Quando o Composer enxerga os pacotes, a instalação em si é um require normal do pacote do tema padrão. Ele puxa o módulo do tema e os outros pacotes base como dependências.

composer require hyva-themes/magento2-default-theme
bin/magento setup:upgrade
bin/magento cache:flush

Depois do setup:upgrade você terá novos módulos habilitados (o módulo do tema Hyvä e suas dependências) e um novo tema registrado como Hyva/default. Nada muda ainda na storefront, porque a store view continua apontando para o Luma ou para o seu tema atual.

Desabilite módulos que o Hyvä não precisa

Alguns módulos do Magento só adicionam código de frontend do Luma. O Hyvä não os usa e alguns é melhor desabilitar em uma loja Hyvä. A documentação do Hyvä mantém a lista atual, então siga ela em vez de uma lista copiada de um post antigo. Desabilite os módulos com bin/magento module:disable em desenvolvimento, faça commit do app/etc/config.php resultante e deixe o seu deploy aplicar.

Crie um child theme desde o primeiro dia

Nunca edite o vendor/hyva-themes/magento2-default-theme e evite usar o Hyva/default diretamente em produção. Um child theme permite atualizar o Hyvä com Composer e manter suas alterações separadas. A estrutura é a mesma de qualquer tema Magento, o que é visto com mais profundidade em criando um child theme no Magento 2.

<?xml version="1.0"?>
<!-- app/design/frontend/Acme/hyva/theme.xml -->
<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">
    <title>Acme Hyva</title>
    <parent>Hyva/default</parent>
</theme>

<?php
// app/design/frontend/Acme/hyva/registration.php
use Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register(ComponentRegistrar::THEME, 'frontend/Acme/hyva', __DIR__);

Depois copie a pasta de build do Tailwind do tema pai para o seu child theme. Essa é a parte que as pessoas perdem. O CSS não é herdado em tempo de build do jeito que os templates são. O seu tema é dono do próprio build e do próprio arquivo de saída.

mkdir -p app/design/frontend/Acme/hyva/web
cp -r vendor/hyva-themes/magento2-default-theme/web/tailwind app/design/frontend/Acme/hyva/web/

Rode o setup:upgrade de novo para o Magento registrar o novo tema e depois atribua-o à store view no admin, em Content, Design, Configuration. Também dá para fazer pela CLI se os seus scripts de deploy gerenciam a config de design, mas o admin serve bem para um primeiro setup.

O build do Tailwind

O Hyvä entrega o CSS como um arquivo compilado. O Tailwind escaneia seus templates, layout XML e JavaScript atrás de nomes de classe e gera apenas o CSS que realmente é usado. Isso significa que uma classe que existe só no banco de dados (por exemplo em um CMS block digitado por um editor de conteúdo) não estará na saída, a menos que o Tailwind consiga vê-la em algum dos paths escaneados, ou você a adicione a uma safelist.

Gere a config dos módulos

Módulos que trazem templates Hyvä podem registrar suas próprias fontes do Tailwind. O módulo do tema Hyvä as reúne em um arquivo JSON para que o build saiba quais pastas de módulo escanear.

bin/magento hyva:config:generate

Isso grava o app/etc/hyva-themes.json. Rode de novo sempre que instalar ou remover um módulo que tenha código de frontend específico do Hyvä. Muitas equipes rodam isso como parte da etapa de build no CI para que nunca fique desatualizado.

Instale e faça o build

cd app/design/frontend/Acme/hyva/web/tailwind
npm ci
npm run build

Os nomes dos scripts npm dependem da versão do Hyvä que você instalou. Releases mais antigas usavam build-prod e watch, as mais novas podem diferir. Abra o package.json na pasta copiada e use os scripts listados ali. Durante o desenvolvimento, rode o script de watch em um terminal separado para o CSS ser refeito quando você salvar um template.

A saída vai para web/css/styles.css dentro do seu tema. O Magento então a trata como qualquer outro asset estático, o que significa que o static content deploy a publica em pub/static.

Você deve commitar o CSS compilado?

Há duas abordagens válidas:

1. Fazer o build no CI. O Node roda no seu pipeline, o styles.css compilado é produzido antes do setup:static-content:deploy e os servidores de produção nunca precisam de Node. É mais limpo e é o que recomendo quando existe um pipeline.
2. Commitar o arquivo compilado. Mais simples para equipes pequenas sem CI, mas você precisa lembrar de refazer o build e commitar a cada mudança de template, e conflitos de merge em um arquivo gerado são chatos.

Qualquer que seja a escolha, a regra é a mesma: o CSS precisa ser construído antes de o static content deploy rodar, ou você publica estilos desatualizados. Se está montando um pipeline, a abordagem de CI/CD para Magento com GitHub Actions funciona bem com uma etapa de Node adicionada antes da etapa de deploy.

Sobrescrevendo templates e layout

Os overrides funcionam como em qualquer tema Magento. Para alterar um template do Hyvä, copie-o do tema pai ou do módulo para o path correspondente no seu child theme.

# override a template that lives in the parent theme
mkdir -p app/design/frontend/Acme/hyva/Magento_Catalog/templates/product/list
cp vendor/hyva-themes/magento2-default-theme/Magento_Catalog/templates/product/list/item.phtml \
   app/design/frontend/Acme/hyva/Magento_Catalog/templates/product/list/item.phtml

Copie só o que você altera. Cada template copiado é um arquivo que você precisa comparar com o do pai a cada upgrade do Hyvä. Um child theme com cem templates sobrescritos deixa os upgrades lentos.

O layout XML também funciona como de costume. Uma coisa específica do Hyvä é que o módulo do tema adiciona layout handles extras com prefixo hyva_ quando um tema Hyvä está ativo, por exemplo hyva_catalog_product_view. Os módulos usam esses handles para aplicar mudanças de layout específicas do Hyvä que não devem afetar uma loja Luma rodando a mesma base de código.

Módulos que ainda não são compatíveis com o Hyvä

Qualquer extensão que adiciona JavaScript de frontend construído em RequireJS, jQuery ou Knockout não vai funcionar em uma página Hyvä do jeito que está. As partes de backend estão ok. Você tem três opções para cada uma: um módulo de compatibilidade, templates Hyvä próprios para aquele módulo ou um fallback Luma para as rotas que precisam. Isso merece planejamento próprio, visto em módulos de compatibilidade do Hyvä.

Durante o setup, faça uma lista de todo módulo de terceiros habilitado que tem saída de frontend. Confira se cada um tem uma versão compatível com o Hyvä do fornecedor antes de escrever qualquer coisa por conta própria.

Checklist de deploy em produção

• Rode o hyva:config:generate e o build do Tailwind antes do static content deploy.
• Faça o deploy do conteúdo estático para o child theme e para os locales que você usa. Restringir o deploy aos temas que você realmente serve o mantém rápido.
• Limpe o full page cache depois da primeira troca. Senão, páginas antigas do Luma continuam sendo servidas pelo Varnish ou pelo cache nativo.
• Confira o mini cart, o estado de login do cliente e as mensagens em uma página cacheada. Isso vem das customer data sections, que o Hyvä lê de forma diferente do Luma.
• Rode o Lighthouse ou o PageSpeed em uma página de categoria e em uma de produto com dados reais, não em um catálogo demo vazio.

bin/magento hyva:config:generate
npm --prefix app/design/frontend/Acme/hyva/web/tailwind ci
npm --prefix app/design/frontend/Acme/hyva/web/tailwind run build
bin/magento setup:static-content:deploy -f --theme Acme/hyva en_US
bin/magento cache:flush

Problemas comuns de setup

A página renderiza sem estilos

Normalmente o child theme não tem um styles.css compilado, ou o static content foi deployado antes de o build rodar. Verifique se o web/css/styles.css existe no seu tema e se o arquivo em pub/static é recente.

Uma classe funciona localmente mas não em produção

A classe é usada em algum lugar que o Tailwind não escaneia, muitas vezes um CMS block ou um módulo que não foi incluído no hyva-themes.json. Adicione o path às fontes de conteúdo ou faça safelist da classe.

Algumas páginas ainda carregam RequireJS

Aquela rota está usando um fallback Luma, ou um módulo está adicionando scripts pelo layout XML. Confira o código-fonte da página e a configuração do fallback.

FAQ

Preciso de Node.js no servidor de produção para o Hyvä?

Não, desde que o Tailwind CSS seja construído antes do deploy, no CI ou em uma máquina de build. A produção só precisa do styles.css compilado que o static content deploy publica.

Posso usar o Hyva/default diretamente sem um child theme?

Funciona, mas qualquer mudança significaria editar arquivos do vendor. Um child theme desde o começo mantém suas alterações seguras nos upgrades do Hyvä.

O que o bin/magento hyva:config:generate faz?

Grava o app/etc/hyva-themes.json com os paths dos módulos que registram fontes de frontend do Hyvä, para que o build do Tailwind escaneie os templates deles atrás de nomes de classe.

Quanto custa uma licença do Hyvä?

O licenciamento e os preços mudaram com o tempo, então confira o hyva.io para os termos atuais em vez de confiar em artigos mais antigos.

Atendo como freelancer em Magento e Hyvä. Se precisar de ajuda para configurar ou migrar uma loja, fale comigo.