Hyvä Theme Folder Structure in Magento 2: A Quick Guide

In online shopping how easy a website is to use can determine if it does well or not. Picking the right theme for your Magento 2 store is very important. The folder structure of the Hyvä theme in Magento 2 is important for store owners and developers. It is known for its simple design and focused on good performance.

The Hyvä Theme is different from regular Magento themes like Luma. It is designed to be simple, fast and easy for developers to use. This makes it very beneficial for online stores. This blog explains the folder setup of the Hyvä Theme. It gives a clear look at its parts, offers technical details, and gives helpful tips for store owners who want to improve their Magento 2 online shops.

We will look at how the Hyvä theme helps developers work faster, improves performance and makes it easy to customize. We will share facts, numbers and real examples to show you how this theme is changing the Magento community.

Why the Folder Structure of the Hyvä Theme Matters

Before we look at the folder structure, let’s see why it’s important. Dutch developer Willem Wigman created Hyvä theme in 2021 and it was made to fix problems with Magento’s default Luma theme. These problems included slow loading, difficult front-end development and old JavaScript libraries like Knockout.js and RequireJS.

As of 2024, more than 3,157 websites around the world use the Hyvä Theme, especially in Europe and North America. This quick growth shows that many stores like it because it helps them create fast and easy-to-use online shops.

The folder setup of the Hyvä Theme is very important for its effectiveness. It removes extra clutter, uses modern tools like Tailwind CSS and Alpine.js and follows Magento’s template system while making changes easier.

For online store owners, understanding this structure is key to:

• Optimizing Development Time: Agencies report saving 20–50% in development time with Hyvä compared to Luma.
• Enhancing Performance: Hyvä achieves near-perfect Google Lighthouse scores (up to 100/100) out of the box.
• Streamlining Maintenance: A clean, modular structure reduces technical debt and simplifies updates.

What is the Basic Folder Structure of a Hyvä Theme?

The Hyvä Theme is set up in the app/design/frontend folder of your Magento 2 system just like other custom themes.

The way it is set up inside is different because it follows a simple design idea. Here is the usual folder arrangement of a Hyvä Theme along with a clear explanation of each part.

app/design/frontend/Hyva/default/

├── composer.json

├── etc/

│   └── view.xml

├── i18n/

├── media/

│   └── preview.png

├── registration.php

├── theme.xml

├── web/

│   ├── css/

│   │   └── styles.css

│   ├── js/

│   │   └── custom.js

│   ├── svg/

│   │   └── icons/

│   ├── fonts/

│   ├── images/

│   ├── tailwind/

│    │  ├── components/

│    │  └── tailwind.config.js

├── Modular_Directory/

│   ├── layout/

│   ├── page/

│   └── module-specific/

1. Root-Level Files

In the main folder of the Hyvä Theme (app/design/frontend/Hyva/default/), you will find important setup files. These files tell how the theme works and what it needs to function.

• composer.json: This file lists what the theme needs to work properly and provides important information. It helps to install the theme using Composer. It includes the PHP version needed and the Magento modules required to make sure everything works well together.
• registration.php: Makes the theme work with Magento so that it can be used as a main design for the website. It typically contains:

php

<?php

use \Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register(

    ComponentRegistrar::THEME,

    'frontend/Hyva/default',

    __DIR__

);

• theme.xml: Defines the theme’s metadata, such as its name, parent theme (if any), and preview image. For example:

xml

<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">

    <title>Hyva Default</title>

    <parent>Magento/blank</parent>

    <media>

        <preview_image>media/preview.png</preview_image>

    </media>

</theme>

These files are critical for integrating the Hyvä Theme into Magento’s ecosystem and ensuring it can be selected via the admin panel under Content > Design > Configuration.

2. etc/ Directory

The etc/ directory contains configuration files, primarily:

• view.xml: Configures image sizes for products, categories, and other elements. This file sets the size of thumbnails and other visual details to keep everything looking the same in the store.

Example:

xml

<view xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xsi:noNamespaceSchemaLocation=”urn:magento:framework:Config/etc/view.xsd”>

    <media>

        <images module=”Magento_Catalog”>

            <image id=”product_page_image_small” type=”small_image”>

                <width>250</width>

                <height>250</height>

            </image>

        </images>

    </media>

</view>

This setup makes it easier to use because it cuts down on the need for a lot of changes to XML files, which is often a problem with Luma-based themes.

3. i18n/ Directory

The i18n/ directory is used for localization, housing translation dictionaries in CSV format. For example, a file like en_US.csv might contain translations for custom strings. This folder is optional and only populated if your store requires multi-language support.

4. media/ Directory

The media/ directory holds the theme’s preview image (preview.png). This image shows up in the Magento admin panel to help identify the theme. It’s a small but important part of choosing a theme.

5. web/ Directory

The web directory is the main part of the Hyvä Theme. It contains styles, scripts, and other fixed resources. It’s organized as follows:

• css/: Contains styling files, with a focus on Tailwind CSS.
  • source/tailwind/: Includes Tailwind configuration (tailwind.config.js) and component-specific styles (components/).
  • styles.css: The main CSS file, compiled from Tailwind utilities and custom styles.
• js/: Houses JavaScript files, primarily Alpine.js for interactivity and custom scripts (custom.js).
• svg/: Stores SVG icons, such as those used for navigation or buttons. Custom icons can be placed in svg/icons/.
• fonts/: Contains custom fonts, if any.
• images/: Stores static images like logos or banners.
• tailwind/: Additional Tailwind-related assets or utilities.

Hyvä uses Tailwind CSS and Alpine.js as part of its modern style. Tailwind CSS keeps the code simple and small while Alpine.js adds easy to use JavaScript features. This replaces bigger libraries like Knockout.js.

6. Modular_Directory/ Directory

The templates directory has PHTML files that create the layout of pages and parts. These files are completely new in Hyvä and use simpler code than Luma. There are also subfolders inside.

• layout/: Layout XML files that define page structure.
• page/: Templates for core pages like the homepage or category pages.
• module-specific/: Templates for specific Magento modules (e.g., Magento_Catalog for product pages).

Hyvä’s PHTML files are made to be simple, making frontend development easier. For instance, a product page template will only include what is necessary, using Tailwind for design and Alpine.js for adding interactive features.

Technical Insights: How the Folder Structure Drives Performance

The folder setup of the Hyvä Theme is not only about being neat; it’s a smart design that helps it work really well. Here are some technical insights backed by data:

1. Reduced Frontend Overhead:
   • Hyvä removes RequireJS, Knockout.js and jQuery because these tools slow down how fast pages load in Luma-based themes. Google’s Core Web Vitals show that Hyvä loads important content in less than one second, while Luma takes 2 to 3 seconds.
   • The web/css/ and web/js/ directories are optimized to include only essential files, reducing the number of HTTP requests.
2. Tailwind CSS Efficiency:
   • Tailwind makes its CSS very small by removing styles that are not used when creating the files. This means that Tailwind CSS files are often less than 10KB in size while Luma themes can be over 100KB.
   • The tailwind.config.js file allows developers to customize Tailwind’s behavior, ensuring only necessary utilities are included.
3. Simplified Templating:
   • Hyvä’s PHTML files in the templates/ folder are 50% shorter than Luma’s. This speeds up how quickly the server can create pages. This is especially helpful for product and category pages that are important for online shopping.
4. Modular Architecture:
   • The Magento_Theme/ folder keeps changes separate from the main Magento files. This helps make updates easier and safer. More than 1,000 Magento 2 add-ons work with Hyvä because it follows Magento’s rules.

Comparing Hyvä’s Folder Structure with Traditional Magento Themes

To fully appreciate the benefits of Hyvä’s folder structure, it’s helpful to compare it with traditional Magento themes:

Feature	Hyvä Theme	Traditional Magento Themes
CSS Framework	Tailwind CSS (utility-first)	LESS (component-based)
CSS Location	web/tailwind/	web/css/source/
JavaScript	Alpine.js	RequireJS + jQuery
Module Organization	Clear module-specific directories	Less clear separation
File Count	40% fewer files	More files with higher complexity
Performance Impact	68% faster page loads (average)	Baseline
Developer Productivity	42% improvement (reported average)	Baseline

This comparison highlights how Hyvä’s structural choices directly impact both performance and development efficiency.

How to Install the Hyvä Theme in Magento 2

To use the Hyvä theme, you need to install it correctly in your Magento 2 setup. Remember, Hyvä is a paid theme so you will need a license to access it.

Steps to Install Hyvä Theme:

1. Get Access

Purchase a Hyvä license from the official website https://hyva.io. You will receive Git access to the private Hyvä repository.

2. Clone the Repository

cd <root_directory_of_setup>

composer config –auth http-basic.hyva-themes.repo.packagist.com token xxxxx

composer config repositories.private-packagist composer https://hyva-themes.repo.packagist.com/project_name/

composer require hyva-themes/magento2-default-theme

3. Set the Theme in Magento

Edit your Magento’s theme.xml and registration.php as needed (usually already included). Then, set it as the default:

bin/magento setup:upgrade

bin/magento setup:di:compile

bin/magento setup:static-content:deploy

You can also set the theme from the Magento Admin Panel:

Content > Design > Configuration > Edit Store View > Select Hyvä Theme

4. Install Dependencies

Hyvä uses Tailwind CSS and Alpine.js, so make sure Node.js and NPM are installed. Then run:

cd vendor/hyva-themes/magento2-default-theme/web/tailwind/

npm install

npm run watch

This will compile Tailwind CSS based on your tailwind.config.js and custom styles.

5. Clear Cache

bin/magento cache:flush

Final Thoughts

The Folder Structure of the Hyvä Theme shows its focus on being simple, fast, and easy for developers to use. Hyvä helps online store owners create great user experiences. It does this by simplifying tools, using new technology, and following a flexible design system from Magento. This means store owners can avoid the extra work that comes with old themes. Knowing this information helps you make smart choices and get the most out of your store if you are starting a new store or moving an old one.

The main point is that Hyvä’s folder setup is important for store owners. It helps you to run your business better. It saves time in building things, makes them work better and allows easy changes. This leads to more sales and happier customers. If you want to learn about Hyvä, begin by looking at its guides, joining the community or working with a Hyvä-certified agency to help you set it up easily.

You are not just changing the way files are organized by using the Hyvä Theme. You are also making your Magento 2 store faster, simpler and more profitable.