Módulos de compatibilidade Hyvä: fazendo extensões Luma funcionarem

Em quase todo projeto Hyvä, o tema é a parte fácil. O trabalho de verdade é a lista de extensões de terceiros que adicionam algo na storefront e foram escritas para o Luma. Cada uma traz módulos RequireJS, widgets jQuery ou templates Knockout que não fazem nada em uma página Hyvä. Este artigo explica como os módulos de compatibilidade funcionam, como decidir entre usar um, escrever um ou cair para o Luma, e como escrever o seu quando não existe nenhum.

Por que extensões Luma quebram no Hyvä

Uma extensão normalmente tem duas metades. A metade de backend (models, plugins, observers, configuração do admin, cron, API) não liga para o tema e funciona no Hyvä sem mudanças. A metade de frontend é o problema. Ela costuma incluir:

• Templates que usam data-mage-init ou x-magento-init para iniciar um widget JavaScript.
• Módulos RequireJS e mixins no requirejs-config.js.
• Templates Knockout e UI components, principalmente para qualquer coisa no mini cart ou no checkout.
• Arquivos LESS que se encaixam no pipeline de estilos do Luma.

O Hyvä não carrega RequireJS, jQuery nem Knockout, e não compila LESS. Então o HTML renderiza, mas nada reage ao usuário, e a estilização some. Às vezes o template em si está bom e só o script está morto. Às vezes o template contém bindings do Knockout e renderiza cru.

As três opções para cada extensão

1. Usar uma versão compatível que já existe. Muitos fornecedores agora entregam suporte a Hyvä, dentro do pacote principal ou como um pacote compat separado. Há também um conjunto de módulos de compatibilidade mantido pela comunidade para extensões populares. Confira as informações de compatibilidade do Hyvä em hyva.io e pergunte ao fornecedor antes de fazer qualquer outra coisa.
2. Escrever um módulo de compatibilidade. Um módulo pequeno que substitui os templates de frontend da extensão original por versões em Alpine.js e Tailwind.
3. Usar um fallback Luma para a rota. Renderizar rotas específicas com um tema baseado em Luma. É adequado para páginas complexas que ainda não valem a reconstrução, tipicamente o checkout ou um configurador custom pesado.

E uma quarta opção que as pessoas esquecem: remover a extensão. A migração é o momento certo para perguntar se cada módulo ainda se paga. Uma auditoria de extensões antes de estimar o trabalho no Hyvä muitas vezes tira vários itens da lista. Se for remover uma, faça direito, como descrito em remover um módulo Magento com segurança.

Como um módulo de compatibilidade funciona

Um módulo de compatibilidade do Hyvä é um módulo Magento comum. O que o torna especial é que ele é registrado como o módulo compat de um módulo original. Quando um tema Hyvä está ativo, o Magento procura os templates do módulo original primeiro no módulo compat. Assim, um template referenciado como Vendor_Module::widget.phtml é servido do view/frontend/templates/widget.phtml do seu módulo compat, se existir lá. O layout XML, os blocks e os view models do módulo original continuam funcionando, só os templates são trocados.

Esse mecanismo vive no pacote de fallback de módulos compat do Hyvä. O registro é uma entrada no di.xml.

<?xml version="1.0"?>
<!-- app/code/Hyva/VendorModule/etc/frontend/di.xml -->
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <type name="Hyva\CompatModuleFallback\Model\CompatModuleRegistry">
        <arguments>
            <argument name="compatModules" xsi:type="array">
                <item name="hyva_vendor_module" xsi:type="array">
                    <item name="original_module" xsi:type="string">Vendor_Module</item>
                    <item name="compat_module" xsi:type="string">Hyva_VendorModule</item>
                </item>
            </argument>
        </arguments>
    </type>
</config>

A convenção de nomes para módulos compat é Hyva_ seguido do vendor e do nome do módulo original. Você pode usar o seu próprio namespace de vendor em módulos compat privados. O que importa é o registro, não o nome.

O module.xml do módulo deve declarar uma sequence no módulo original e no Hyva_CompatModuleFallback, e o composer.json deve exigir os dois pacotes.

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="Hyva_VendorModule">
        <sequence>
            <module name="Vendor_Module"/>
            <module name="Hyva_CompatModuleFallback"/>
        </sequence>
    </module>
</config>

Escrevendo os templates compat

Comece achando todos os templates que o módulo original renderiza na storefront. O jeito mais rápido é habilitar os template path hints em uma loja de desenvolvimento, ou procurar na pasta view/frontend/layout do módulo por atributos template= e chamadas setTemplate.

Para cada template:

1. Copie para o módulo compat no mesmo caminho relativo.
2. Remova todo data-mage-init, script x-magento-init e binding do Knockout.
3. Refaça a interação com um componente Alpine no mesmo template. Os padrões para isso estão em escrevendo componentes Alpine.js no Hyvä.
4. Troque a estilização em LESS por classes utilitárias do Tailwind.
5. Mantenha os métodos de block que o template original chamava. Se alguma lógica do JavaScript original deveria mesmo estar no servidor, adicione um view model no módulo compat.

Leia com cuidado o JavaScript original antes de reescrevê-lo. Muitas vezes ele contém regra de negócio que não é óbvia pelo template: um endpoint AJAX, um recálculo de preço, uma dependência de uma customer data section. Cada uma delas precisa ser reproduzida, senão a feature muda de comportamento em silêncio.

Mudanças de layout só para o Hyvä

Às vezes um template não basta e você precisa remover ou mover um block só no Hyvä. Use os layout handles com prefixo hyva_, que o módulo do tema Hyvä adiciona junto dos handles normais quando um tema Hyvä está ativo. Um arquivo chamado hyva_catalog_product_view.xml no módulo compat se aplica só às páginas de produto do Hyvä, então a mesma base de código ainda consegue servir uma store view Luma sem efeitos colaterais.

<?xml version="1.0"?>
<!-- view/frontend/layout/hyva_catalog_product_view.xml -->
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceBlock name="vendor.module.product.legacy.js" remove="true"/>
    </body>
</page>

Registrando o módulo no build do Tailwind

Seus templates compat usam classes do Tailwind, então o build do tema precisa escaneá-los. Os módulos registram seu caminho por um observer no evento hyva_config_generate_before, e o bin/magento hyva:config:generate grava o resultado em app/etc/hyva-themes.json. O observer adiciona uma entrada na lista extensions do objeto de config passado no evento.

<?php
declare(strict_types=1);

namespace Hyva\VendorModule\Observer;

use Magento\Framework\Component\ComponentRegistrar;
use Magento\Framework\Event\Observer;
use Magento\Framework\Event\ObserverInterface;

class RegisterModuleForHyvaConfig implements ObserverInterface
{
    public function __construct(
        private readonly ComponentRegistrar $componentRegistrar
    ) {
    }

    public function execute(Observer $observer): void
    {
        $config = $observer->getData('config');
        $extensions = $config->hasData('extensions') ? $config->getData('extensions') : [];

        $path = $this->componentRegistrar->getPath(ComponentRegistrar::MODULE, 'Hyva_VendorModule');
        $extensions[] = ['src' => substr($path, strlen(BP) + 1)];

        $config->setData('extensions', $extensions);
    }
}

Confira a documentação do Hyvä da versão que você roda para confirmar onde o observer do evento deve ser declarado e se o seu módulo também precisa de um arquivo próprio de config do Tailwind. Refaça o build do CSS do tema depois de adicionar o módulo.

Usando o fallback Luma

O pacote de fallback pode renderizar rotas selecionadas com um tema baseado em Luma. Ele é configurado no admin, nas configurações do Hyvä, onde você o habilita, escolhe o tema de fallback e lista os paths das rotas. O checkout é o caso comum. Outros bons candidatos são páginas de uma extensão com muito código Knockout que poucos clientes usam, por exemplo um portal de devoluções na conta do cliente.

Lembre o que você paga por cada rota de fallback:

• Um segundo tema para manter, com estilização própria que precisa ficar parecida o bastante com o tema Hyvä.
• JavaScript completo do Luma nessas páginas, o que significa carregamentos mais lentos ali.
• Deploy de conteúdo estático para os dois temas, o que deixa os deploys mais longos.

Trate as rotas de fallback como temporárias, a menos que haja um bom motivo. Coloque no backlog com um plano.

Estimando o trabalho de compatibilidade

Para a estimativa de uma migração, monte uma tabela com uma linha por extensão que tenha saída de frontend. Para cada uma, registre se existe versão compatível, quantos templates ela renderiza, quanto JavaScript tem e quais páginas afeta. Um módulo com um template e um toggle é uma hora. Um módulo com um configurador de produto movido a Knockout pode levar semanas. A maioria dos estouros de estimativa em projetos Hyvä vem de subestimar essa lista, não o tema em si. O lado da migração está no plano de migração do Luma para o Hyvä.

Mantendo seus módulos compat

Um módulo compat copia templates de outro fornecedor. Quando esse fornecedor lança uma versão nova, os templates dele podem mudar e os seus não. Fixe as versões das extensões no composer.json e, a cada atualização, compare os templates de frontend do módulo original com a versão anterior. Se algo mudou, leve para o seu template compat. Se você publica um módulo compat de uma extensão pública, considere contribuir com o conjunto da comunidade para que outros dividam a manutenção.

FAQ

Preciso de um módulo de compatibilidade para extensões sem frontend?

Não. Extensões só de admin e de backend, como conectores de ERP, cron jobs e integrações de API, funcionam no Hyvä sem mudanças.

Como o Magento sabe que deve usar os templates do meu módulo compat?

O módulo compat é registrado no Hyva\CompatModuleFallback\Model\CompatModuleRegistry pelo di.xml. Quando um tema Hyvä está ativo, os templates do módulo original são procurados primeiro no módulo compat.

O fallback Luma é uma solução de longo prazo?

Pode ser, principalmente para o checkout, mas cada rota de fallback significa um segundo tema para estilizar e manter e páginas mais lentas nessas rotas. A maioria das equipes trata como uma etapa da migração.

Onde encontro módulos de compatibilidade que já existem?

Pergunte primeiro ao fornecedor da extensão, depois confira as informações de compatibilidade do Hyvä e os módulos compat da comunidade linkados no hyva.io.

Atendo como freelancer em Magento e Hyvä, incluindo módulos de compatibilidade. Se precisar de ajuda com isso, fale comigo.