Magento Hyvä theme in the developer’s eyes

A few months ago, we wrote about Hyvä which brings a fresh breeze to Magento themes. It can drastically improve Magento store performance which can be a huge improvement for store owners. This time, let’s have a look at Magento Hyvä theme from a Magento developer’s point of view.

In the specific project, I’ll be talking about, we only used Hyvä for the frontend. However, it’s worth noting that you can also use Hyvä for the checkout (Hyvä_Checkout) and the admin panel (Hyvä_Admin). In our project, we only used Hyvä to create new grids and forms. It does not impact the actual Magento admin panel.

What’s new?

The most notable change Hyvä brings is replacing KnockoutJS with AlpineJS. I will write about what does it mean for us later. Regarding the stylesheet, Hyvä uses TailwindCSS.

This means a whole new approach to writing JS and styles. This also means we need to take a new approach to building assets. Hyvä uses PostCSS and to build the assets we need to run npm run, build-dev, or build-prod command. This is not very time-consuming and the build happens really quickly. Having a watch by default would be great but unfortunately, you need to figure it out yourself. However, the Hyvä documentation shows how to configure Browsersync. It automatically refreshes the browser on multiple devices every time the project files are changed.

What’s not new?

Now that we know what’s new, let’s have a look at what stayed the same. There are well-known Magento XML layouts with Blocks and PHTML templates. In this department, creating the theme is unchanged. There are some special cases, though, e.g. when you want to add a Tailwind class directly to an XML layout. Specifically, it concerns a situation when you’re passing classes with the htmlClass parameter. If you type a Tailwind class, e.g. w-full, it will be accepted but e.g. w-1/2 will not because of the forbidden sign /. One workaround here is to aggregate Tailwind classes to our own class and using it in the layout XML file.

Listen to us talk about Hyvä on the Talk Commerce podcast!

Third-party integrations

It is a good idea to start with reading the documentation. You may learn that Hyvä doesn’t support all Magento modules yet and some have to be turned off – Dotdigitalgroup_Email, Dotdigitalgroup_Chat, and Dotdigitalgroup_Sms.

Hyvä uses its own „ReCaptcha V3 invisible” implementation. This means that the default Magento one has to be disabled, e.g. with the following command: bin/magento config:set customer/captcha/enable 0

Otherwise, the captcha won’t let the form come through.

Getting Started with Magento Hyvä Theme

After installing Magento and Hyvä, we started work on the new theme by copying all files from the original vendor/hyva-themes/magento2-default-theme/web/ to the correct web catalog in app/design/frontend/. Everything from the web catalog has to be copied – even the files that you think you won’t use in the project. Once you’re set up, you can start working on the theme by modifying the templates in their respectable modules.

Here, you can place most of the styles directly in the PHTML templates without the need of adding new CSS files. This is the approach that the Hyvä creators seem to take as well. Place the Tailwind classes in HTML – easy as that. Of course, there are also separate CSS files organized in a structure of components (like buttons, forms, messages, slider, typography, etc.) and a structure of a page template (like header, footer, page, etc.). You can add your own CSS files and create class sets inside them. There, you can use @apply to place the Tailwind classes which improves the reusability of the same Tailwind style sets that tend to be very long.

Configuring Tailwind

Of course, you can configure Tailwind to the needs of your project using the tailwind.config.js file. Especially, the “purge” configuration deserves special mention. When you build the assets with the build-dev command, all classes are attached to CSS files. However, if you build with build-prod (to a target environment), you may be surprised to see that the store doesn’t look right. It’s because Hyvä purges CSS when compiling styles for the theme. The Purging script finds all Tailwind classes you used in your theme and uses the one from the original, complete Tailwind stylesheet. This way, when building for production, the CSS file only contains the Tailwind styles that were found in your templates. It’s a great way to optimize the CSS file.

However, as I mentioned it can create a problem with some classes missing in the final build. To solve it, you can copy the required templates from hyva-themes to your theme or use the “purge” configuration in the tailwind.config.js file. To do this, indicate the paths to the templates you’re using in the theme, e.g. you can add the path to the original hyva-themes from the vendor catalog:

module.exports = {
  ...
  purge: {
    content: [
        '../../../../../../../vendor/hyva-themes/magento2-default-theme/**/*.phtml',
        ...
    ]
  }
}

This should solve the problem.

AlpineJS

AlpineJS is a modern lightweight JS library. It lets you create the required JS directly in the templates they’re used in. It makes the programming easier in comparison to Knockout.js. You don’t have to waste time searching for the JS and HTML files responsible for a given PHTML template. In Konckout.js, it’s often problematic and binded in a hardly readable way. With AlpineJS, everything is in one place and easy and clear bindings of JS data with HTML improves development.

This solution has its downsides, too. All Knockout-based solutions no longer work and you have to write them in AlpineJs from scratch which can be very arduous. It also prevents you from using third-party solutions that are based on Knockout.js and don’t have a Hyvä implementation yet.

However, more and more solutions show up in the Hyvä repository (Compatibility Module Tracker), so the most popular extensions are always being added.

There is also Hyvä Demo, which we found helpful if only to compare our custom theme with Native Hyvä.

Magento Hyvä Theme: Developer’s summary

Hyvä provides a new approach to creating styles and scripts which greatly improve the Magento store performance (read how we increased mobile Lighthouse performance from 10 to 97). From the developer’s point of view, AlpineJS is way more friendly and makes writing JavaScript easier.