Wdrożenie Hyva Theme w Magento 2 – Alpine.js, Tailwind CSS, Lighthouse 100

Hyva Theme (hyva.io) to komercyjny motyw dla Magento 2, który zastępuje cały stos frontendowy Luma. Zamiast Knockout.js, RequireJS i tysięcy plików JS, Hyva używa Alpine.js (reaktywność UI) i Tailwind CSS (stylowanie). Efekt? Kod frontend jest czytelny, kompilacja trwa sekundy, a Google Core Web Vitals osiągają zielone wskaźniki bez dodatkowych optymalizacji.

Luma vs Hyva – porównanie stacków

Poniższa tabela pokazuje, czym różni się klasyczny stos Luma od Hyva. Różnica w wadze JS to główny powód, dla którego Luma nigdy nie osiągnie dobrych wyników Core Web Vitals na urządzeniach mobilnych.

Aspekt	Luma (klasyczny)	Hyva Theme
Framework JS	Knockout.js + RequireJS (~300KB)	Alpine.js (~15KB)
CSS	LESS, wielokrotnie kompilowany (>500KB)	Tailwind CSS (purge, <50KB)
Lighthouse (mobile)	30–60 (typowo)	90–100 (out of box)
Szablony	XML layout + .phtml + Knockout bindings	Uproszczone .phtml + Alpine directives
Kompilacja	setup:static-content:deploy (minuty)	npm run build-prod (<30s)
Licencja	Open Source (Magento)	Komercyjna (jednorazowa opłata per projekt)

Instalacja Hyva przez Composer

Hyva Theme jest dystrybuowana przez prywatne repozytorium Composer. Po zakupie licencji otrzymujesz token dostępu, który należy dodać do auth.json. Sam motyw instaluje się jak standardowy pakiet Magento 2.

Instalacja Hyva Theme krok po kroku

Instalacja przez Composer wymaga dostępu do repozytorium hyva.io. Poniższy przykład zakłada że masz już Magento 2.4.8 z PHP 8.3.

# 1. Dodaj repozytorium Hyva do composer.json:

composer config repositories.hyva-themes composer https://repo.hyva.io

# 2. Dodaj token autoryzacji (z panelu hyva.io):

composer config --auth http-basic.repo.hyva.io TOKEN_UZYTKOWNIK TOKEN_HASLO

# 3. Zainstaluj core motywu i komponent modulów:

composer require hyva-themes/magento2-default-theme

composer require hyva-themes/magento2-hyva-modules

# 4. Aktywuj moduły Hyva w Magento:

php bin/magento module:enable Hyva_Theme Hyva_ThemePageBuilder

php bin/magento setup:upgrade

# 5. Ustaw motyw w Admin: Content > Design > Configuration:

php bin/magento config:set design/theme/theme_id ID_MOTYWU --scope=store --scope-code=default

Tailwind CSS i Alpine.js – twój nowy workflow

Po instalacji Hyva motyw tworzy katalog app/design/frontend/Hyva/default/web/tailwind/. Tam znajdziesz plik tailwind.config.js ze skonfigurowanymi Ŝieżkami do wszystkich plików .phtml i .xml, które Tailwind skanuje pod kątem używanych klas.

Pro Tip: Tailwind JIT + własny motyw potomny

Nigdy nie modyfikuj plików bezpośrednio w katalogu vendor/hyva-themes/. Utwórz własny motyw potomny (child theme), który dziedziczy z Hyva i nadpisuje tylko to, co potrzebujesz. W ten sposób aktualizacje Hyva nie nadpiszą Twoich zmian.

# Utwórz motyw potomny (Vendor/mytheme):

mkdir -p app/design/frontend/Vendor/mytheme

# app/design/frontend/Vendor/mytheme/theme.xml:

<title>Mój Sklep Theme</title>

<parent>Hyva/default</parent>

</theme>

# Kompilacja CSS w trybie watch (deweloperski):

cd app/design/frontend/Vendor/mytheme/web/tailwind

npm install && npm run watch

# Produkcyjny build (przed deploymentem):

npm run build-prod

Kompatybilność modułów z Hyva

Najważniejsza rzecz przed migracji na Hyva: nie wszystkie moduły Magento działają automatycznie. Moduły, które mają własny frontend (np. Amasty, Smile Elasticsearch, module płatności), wymagają dodatkowego pakietu kompatybilności. Społeczność Hyva tworzy i udostępnia setki takich modułów za darmo.

hyva-themes/magento2-hyva-compat

Oficjalne repozytorium modułów kompatybilności. Znajdziesz tu wsparcie dla Amasty, Mirasvit, Smile i dziesiątek innych vendorów.

Moduły backendowe – działają bez zmian

Moduły, które dotykają tylko logiki PHP i API (ERP, PIM, inventory) działają z Hyva bez żadnych modyfikacji.

Hyva Checkout

Osobny produkt zastepujący klasyczny checkout Magento. Jeszcze lepsze wyniki Lighthouse i pełna integracja z bramkami płatności przez dedykowane adaptery.

GraphQL + PWA – niezależne

Jeśli używasz Venia (PWA Studio) lub Vue Storefront, Hyva Theme nie koliduje – są to niezależne warstwy prezentacji.

Najczęstsze problemy przy wdrażaniu Hyva

Moduł płatności nie wyświetla się w checkout

Brak modułu kompatybilności Hyva. Sprawdź repozytorium hyva-compat lub zamów dedykowany adapter od dostawcy modułu.

CSS po deploymencie nie zawiera nowych klas

Zapomniano o uruchomieniu npm run build-prod przed deploymentem. Tailwind nie włączył nowych klas do purge output.

Alpine.js: "x-data not defined"

Brakuje definicji komponentu x-data lub komponent został zdefiniowany poza zakresem, gdzie Alpine go szuka. Sprawdź kolejność inicjalizacji.

PageBuilder nie renderuje bloków

Wymagany dodatkowy pakiet hyva-themes/magento2-hyva-theme-pagebuilder. Bez niego bloki PageBuilder nie wyświetlają się poprawnie w Hyva.

Modyfikacje w vendor/ nadpisywane przy update

Edytowano pliki bezpośrednio w vendor/hyva-themes/. Każdy composer update nadpisze zmiany. Użwaj child theme.

Lighthouse nie pokazuje 100 po wdrożeniu

Często problem leży po stronie hostingu (TTFB >200ms) lub niezoptymalizowanych obrazków. Hyva daje świetny frontend, ale serwer też ma znaczenie.

Diagnostyka – sprawdzanie stanu Hyva Theme

Jeśli coś nie działa po instalacji Hyva, te komendy pomogą zlokalizować problem.

# Sprawdź czy moduły Hyva są aktywne:

php bin/magento module:status | grep -i hyva

# Sprawdź przypisany motyw do sklepu:

php bin/magento config:show design/theme/theme_id

# Wyczyść cache po zmianie motywu lub CSS:

php bin/magento cache:flush full_page layout block_html

php bin/magento setup:static-content:deploy -f pl_PL en_US

# Sprawdź, która wersja Hyva jest zainstalowana:

composer show hyva-themes/magento2-default-theme | grep versions

# Lista zainstalowanych pakietów kompatybilności Hyva:

composer show | grep hyva

Hyva Theme to najlepsza decyzja frontendowa, jaką możesz podjąć dla Magento 2 w 2025 roku. W Mage24.pl każde nowe wdrożenie uruchamiamy na Hyva – czas developmentu krótszy o połowę, wyniki Lighthouse wzorowe, a klient zadowolony z szybkości sklepu.

Hyva Theme: Lighthouse 100 na Dzień Dobry