Introduction to Hyvä Theme Development
According to the built with trend Hyvä reduces JavaScript bundle size by up to 90%+ compared to Luma-based themes.
If you have been working with Magento 2 for any amount of time, you already know how painful the default frontend can be. Slow page loads, bloated JavaScript, and Core Web Vitals scores that make you helpless. This is exactly the problem Hyvä Theme was built to fix, and it has become the go-to frontend solution for serious Magento developers around the world.
In this guide, you will get a complete, practical walkthrough of how to create your own custom Hyvä Theme in Magento 2 from scratch, including file structure, configuration, Tailwind CSS setup, deployment, and troubleshooting.
What is Hyvä Theme in Magento 2?
Hyvä Theme is a modern frontend framework built specifically for Magento 2. Instead of relying on the traditional Magento frontend stack that is loaded with RequireJS, KnockoutJS, and heavy CSS libraries, Hyvä strips all of that away and replaces it with two powerful and lightweight tools: Tailwind CSS for utility-based styling and Alpine.js for reactive interactivity.
The result is a Magento storefront that loads dramatically faster, consumes less bandwidth, and delivers a much cleaner developer experience. Hyvä is not just a theme, it is a completely different way of thinking about Magento frontend development.
Hyvä stores load 2–5× faster than Luma-based stores.
Is your Magento store not lightning-fast yet? Let’s grow your site with Hyvä for unmatched speed and performance.
Benefits of Using Hyvä for Custom Theme Development
- Faster performance with reduced JavaScript and page size
- Improved Core Web Vitals scores
- Simplified development using Tailwind CSS and Alpine.js
- Easy customization with Magento child theme structure
- Growing ecosystem with active support and updates
Why choose Hyvä over Luma in Magento 2?
Hyvä is better than Luma because it removes unnecessary JavaScript, improves performance, and simplifies Magento 2 frontend development.
Here are the key reasons Magento store owners choose the Hyvä Theme over the default Magento Luma theme.
- Loads pages significantly faster with reduced dependencies
- Improves Core Web Vitals (LCP, TTI, CLS)
- Delivers better user experience with faster interactions
- Simplifies development by eliminating RequireJS complexity
- Uses modern technologies like Tailwind CSS and Alpine.js
- Reduces debugging time and improves code readability
Prerequisites for Creating a Hyvä Theme in Magento 2
Before starting, make sure your Magento environment meets these requirements.
Magento Version Compatibility
The magento hyva theme supports Magento Open Source and Adobe Commerce. The current compatibility matrix is:
Magento Version Compatibility
The Hyvä Theme supports both Magento Open Source and Adobe Commerce. The recommended versions include:
- Magento 2.4.4-p9
- Magento 2.4.5-p8
- Magento 2.4.6-p7
- Magento 2.4.7-p1 or higher
Always verify the latest compatibility updates from the official Hyvä documentation before proceeding.
System Requirements
- PHP: 7.4, 8.1, 8.2, 8.3, or 8.4
- Composer: Version 2.x
- Node.js: 16+ (required for Tailwind CSS compilation)
- NPM or Yarn for frontend build tools
Hyvä License & Access
- A valid Hyvä license is required
- A Hyvä Packagist key is needed to install the theme
Install Hyvä Theme in Magento 2
To install the base Hyvä Theme in Magento 2, you first need to add your Packagist authentication key, register the Hyvä private repository with Composer, and then require the default theme package.
Start by running this command to add your authentication credentials:
composer config --auth http-basic.hyva-themes.repo.packagist.com token yourLicenseAuthenticationKey
Then add the Hyvä Composer repository:
composer config repositories.private-packagist composer https://hyva-themes.repo.packagist.com/yourProjectName/
Now install the default Hyvä theme:
composer require hyva-themes/magento2-default-theme
If you are looking for how to install the Hyvä Theme in Magento 2 step by step, explore this guide: How to Install Hyvä Themes in Magento 2
Now install the default Hyvä theme:
composer require hyva-themes/magento2-default-theme
After the package installs, run the Magento setup upgrade:
bin/magento setup:upgrade
Once the installation is complete, go to your Magento Admin Panel. Navigate to Content → Design → Configuration, and activate the Hyvä default theme for your store view.
With the base theme active, you are now ready to create your own custom child theme on top of it.
Understanding Hyvä Theme Structure
Before creating any files, it is important to understand how the Hyvä Theme is structured. This foundational knowledge will help reduce debugging time and improve development efficiency.
Default Hyvä Theme Architecture
The Hyvä default theme is located in the vendor directory at the following path:
vendor/hyva-themes/magento2-default-theme/
This directory follows the standard Magento theme structure with additional Hyvä-specific enhancements. The most critical subdirectory is the web folder, which contains:
- Tailwind CSS configuration
- Compiled CSS output
- Alpine.js-related files
Template files and layout XML follow Magento’s default conventions. If you are familiar with Magento theming, you can work with Hyvä without starting from scratch.
Parent and Child Theme Concept
Hyvä uses Magento’s native parent-child theme inheritance model. When you create a child theme and set Hyva/default as the parent, Magento automatically falls back to the parent theme for any files not overridden in the child theme.
This approach ensures:
- Minimal code duplication
- Easier maintenance
- Seamless updates when new Hyvä versions are released
Key Directories and Files Explained
The following files are essential when creating a custom Hyvä theme:
- theme.xml – Defines the theme name and parent theme
- registration.php – Registers the theme with Magento
- composer.json – Declares the theme as a Composer package
- web/ – Contains Tailwind CSS configuration, compiled styles, and custom JavaScript
- templates & layout XML – Follow Magento’s standard module-based structure for overrides
Step-by-Step Guide to Create Custom Hyvä Theme in Magento 2
Now let’s create a custom child theme. In this example, we will create a theme named hyva_child under the vendor namespace iCreative . You can replace these names with your own.
Step 1: Create a New Theme
Create the following directory inside your Magento installation:
app/design/frontend/icreative/hyva_child/
This follows Magento’s standard theme structure:
app/design/frontend/VendorName/ThemeName
Pro tip for production stores: Always run setup:static-content:deploy with your specific locale flags to avoid deploying unnecessary locales. For example: php bin/magento setup:static-content:deploy en_US -f
Step 2: Define Theme Registration Files
Every Magento theme requires two essential files:
- theme.xml
- registration.php
These files inform Magento about the existence and configuration of your custom theme.
Step 3: Configure theme.xml and registration.php
Create the theme.xml file at the following location:
This file defines your theme and links it to the Hyvä parent theme.
app/design/frontend/iCreative/hyva_child/theme.xml
Theme.xml
Create this file at:
app/design/frontend/iCreative/hyva_child/theme.xml
<?xml version="1.0"?>
<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">
<title>ICreative Hyva ChildTheme</title>
<parent>Hyva/default</parent>
</theme>
Registration.php
Create this file at:
app/design/frontend/iCreative /hyva_child/registration.php
<?php
use Magento\Framework\Component\ComponentRegistrar;
ComponentRegistrar::register(
ComponentRegistrar::THEME,
'frontend/iCreative/hyva_child',
__DIR__
);
After Creating These Files
Run the following Magento commands:
php bin/magento setup:upgrade
php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush
Then activate your theme from:
Admin → Content → Design → Configuration
Registration.php
To properly structure your custom theme as a Composer package (recommended for scalability and deployment workflows), create a composer.json file inside your theme directory.
{
"name": "iCreative/hyva-child-theme",
"description": "Custom Hyva child theme for Magento 2",
"type": "magento2-theme",
"require": {
"php": ">=7.4"
},
"autoload": {
"files": [
"registration.php"
]
},
"extra": {
"map": [
[
"*",
"iCreative/hyva_child"
]
]
}
}
Step 4: Set Parent Theme (Hyva/default)
The parent theme is already declared in theme.xml with the line <parent>Hyva/default</parent>. This is what links your child theme to the Hyvä base theme.
One important thing to note here: the parent identifier must be exactly Hyva/default with that specific casing. Using incorrect casing is a common mistake that causes the theme to not load properly.
Now copy the web folder from the Hyvä default theme into your child theme. This is required for Tailwind CSS compilation to work correctly:
cp -r vendor/hyva-themes/magento2-default-theme/web/ app/design/frontend/iCreative/hyva_child/web/
Step 5: Run Magento Setup Commands
With all theme files in place, run the following commands to register the theme and deploy assets:
bin/magento setup:upgrade
bin/magento cache:clean
bin/magento cache:flush
```
After these commands complete, go to Content, then Design, then Configuration in your Magento Admin Panel, select your new Hyvä child theme from the dropdown, and save the configuration.
---
## Customizing Your Hyvä Theme
With the child theme active, you can now start customizing it. Hyvä follows standard Magento conventions for template and layout overrides, so if you have worked with Luma-based themes before, most of this will feel familiar.
### Modifying Layout XML Files
To override a layout XML file from the Hyvä default theme or from any Magento module, create the corresponding file in your child theme under the same path it would appear in the module.
For example, to override the catalog product view layout, create:
```
app/design/frontend/iCreative/hyva_child/Magento_Catalog/layout/catalog_product_view.xml
```
Your overrides will be merged on top of the parent theme and module layout XML files during the layout building process.
### Customizing Templates (.phtml)
Template overrides work the same way. To override a .phtml file from the Hyvä theme or from a Magento module, mirror the file path inside your child theme directory.
For example, to override the product name template:
```
app/design/frontend/iCreative/hyva_child/Magento_Catalog/templates/product/view/name.phtml
```
Magento will use your version of the file instead of the parent theme version. Only copy files you actually need to change. Keeping unnecessary copies of template files makes upgrades more difficult.
### Working with Tailwind CSS in Hyvä
This is where Hyvä Theme development differs from standard Magento theming. Hyvä uses Tailwind CSS, which means styles are generated at compile time based on the classes found in your template files.
Open the Tailwind configuration file in your child theme:
```
app/design/frontend/iCreative/hyva_child/web/tailwind/tailwind.config.js
In the content or purge section, add the path to the parent theme templates so Tailwind scans them while generating CSS:
content: [
'../../**/*.phtml',
'../../*/layout/*.xml',
'../../../../../../../vendor/hyva-themes/magento2-default-theme/**/*.phtml',
'../../../../../../../vendor/hyva-themes/magento2-default-theme/*/layout/*.xml',
]
This ensures that Tailwind CSS classes used in parent theme templates are not stripped out during the purge step.
To install Tailwind dependencies, navigate to the tailwind directory and run:
npm install
During development, use watch mode to compile styles automatically as you make changes:
npm run watch
For production, build optimized and minified styles:
npm run build-prod
Adding Custom Styles and Scripts
You can add custom CSS beyond what Tailwind generates by creating a styles directory in your web folder and including it through a layout XML file or directly in the default_head_blocks.xml override.
For custom JavaScript, Hyvä uses Alpine.js for component-level interactivity. You can define custom Alpine.js components directly in your .phtml templates using inline script tags, or load them as separate JavaScript files through layout XML.
Why Hyvä Theme is Best for Magento 2 Speed Performance Optimization?
Hyvä’s performance advantage is not accidental. It is the direct result of removing the frontend dependencies that have historically made Magento slow.
Why Hyvä is Faster Than Luma?
Luma loads RequireJS, KnockoutJS, jQuery UI, and several other libraries just to render a basic storefront page. These JavaScript files are large, blocking, and often completely unnecessary for the specific page being viewed.
Hyvä replaces all of this with Alpine.js, which is a fraction of the size of KnockoutJS. Tailwind CSS generates only the styles that are actually used in your templates. The result is dramatically smaller page payloads, fewer render-blocking resources, and much faster Time to Interactive scores.
Best Practices for Hyva Theme Speed Optimization
To fully leverage the performance capabilities of the Hyvä Theme in Magento 2, it is essential to follow structured optimization practices aligned with modern frontend architecture and Core Web Vitals.
Key Optimization Practices:
- Run production builds before deployment – Always execute npm run build-prod prior to going live. This activates Tailwind CSS purge, eliminating unused utility classes and significantly reducing the final CSS bundle size.
- Limit third-party scripts –
Avoid injecting unnecessary external scripts through layout XML. Each additional script increases network requests, blocks rendering, and negatively impacts performance metrics. - Implement lazy loading for media – Use the loading=”lazy” attribute for product and content images below the fold. This reduces initial page load time and improves Largest Contentful Paint (LCP).
- Optimize Alpine.js usage – Keep Alpine.js components modular and lightweight. Avoid deeply nested reactivity structures unless required, as they can introduce unnecessary complexity and processing overhead.
Testing and Deploying Your Custom Hyva Theme
Enabling Developer Mode
Before testing, switch Magento to developer mode. This disables caching of compiled files and makes debugging significantly easier:
bin/magento deploy:mode:set developer
In developer mode, Magento regenerates static files on each page request, so changes to templates and layout XML are reflected immediately without needing to re-deploy static content.
Static Content Deployment
When you are ready to move to production or staging, take a backup of your pub/static directory first. Then clean the existing static files and deploy fresh:
rm -rf pub/static/frontend/
php bin/magento setup:static-content:deploy -f
For multilingual stores, specify language codes:
php bin/magento setup:static-content:deploy en_US en_GB -f
Before deploying static content, make sure you have run npm run build-prod inside your child theme’s tailwind directory. The compiled CSS file at web/tailwind/css/output.css must exist before static content deployment.
Cache Management and Testing:
After deployment, flush all caches:
bin/magento cache:clean
bin/magento cache:flush
Test your theme across all key pages: homepage, category pages, product detail pages, cart, and checkout. Pay specific attention to how Alpine.js components behave, since most Hyvä interactivity depends on them loading correctly.
Use Chrome DevTools to verify that no legacy JavaScript libraries like RequireJS or KnockoutJS are loading on your Hyvä pages. If they are, an extension is likely injecting them.
Hyvä Theme Troubleshooting Guide (Fix Common Magento 2 Issues)
- Theme Not Showing Issue
Solution – If your child theme does not appear in the Design Configuration dropdown, the most likely cause is a missing or incorrectly formatted registration.php file. Double-check the theme path string inside
ComponentRegistrar::register matches your actual directory path exactly.
Also verify that you have run bin/magento setup:upgrade after adding the theme files. Magento needs to scan and register new theme components during setup.
2) Static Files Not Loading
If CSS or JavaScript is not loading correctly after deployment, check the following things in order.
First, confirm that output.css exists at app/design/frontend/iCreative/hyva_child/web/tailwind/css/output.css. If this file is missing, Tailwind has not been compiled. Run npm install followed by npm run build-prod inside the tailwind directory.
Second, verify that pub/static files were actually deployed for your theme and locale. Check pub/static/frontend/iCreative/hyva_child/ for your compiled assets.
Third, check file permissions. Static files in pub/static need to be readable by the web server.
3) Cache and Compilation Errors
If you are seeing errors about missing CSS or layout issues after making template changes, clear compiled code and regenerate:
bin/magento cache:clean
bin/magento cache:flush
rm -rf generated/code
bin/magento setup:di:compile
Hyvä Theme Development Best Practices for Magento 2
- Maintain Clean Code Structure
Only include files in your child theme that you actually need to override. Every file you copy from the parent theme becomes a file you are responsible for maintaining. When Hyvä releases updates, files you have copied locally will not receive those updates automatically.
2. Follow Magento Coding Standards
Hyvä templates are still Magento .phtml files, which means the same escaping, translation, and coding standards apply. Always use $escaper->escapeHtml() for output escaping. Use $block->trans() or __() for translatable strings. Keep business logic out of templates.
3. Optimize for SEO and Core Web Vitals
Hyvä gives you a strong head start on Core Web Vitals, but there are additional things you can do to push scores further.
Preload your primary fonts using link rel=”preload” in the theme head. Avoid adding large hero images above the fold without proper sizing and compression. Use width and height attributes on all img tags to eliminate Cumulative Layout Shift. Minimize the number of custom Alpine.js components that initialize on page load if they are not immediately needed.
iCreative Technologies — Leading Hyvä Theme Agency in USA & Germany
iCreative Technologies is a leading Hyvä Theme development agency, delivering premium Hyvä Theme services in the USA and across Europe, including Germany, the Netherlands, France, and Italy.
With a team of certified Hyvä developers, the company specializes in building high-performance, lightning-fast Magento 2 storefronts powered by the Hyvä Theme. Its development approach focuses on speed optimization, clean architecture, and scalable frontend solutions tailored for modern eCommerce.
We have a proven decade of experience as a leading Hyvä theme development company.
Looking to migrate to Hyvä Theme or need a custom Hyvä store development partner? Let’s get started with a free 30-minute strategy call.
FAQs – Create Hyva Theme
The Hyvä Theme is a modern frontend solution for Magento 2 that replaces Luma with a lightweight stack using Tailwind CSS and Alpine.js. It improves performance, simplifies development, and enhances user experience.
To create a custom Hyvä theme, you need to create a child theme under app/design/frontend, define theme.xml and registration.php, set Hyva/default as the parent theme, and deploy static content.
The Hyvä license typically costs around €1,000 (one-time fee) per Magento installation.
Key pricing insights:
- One-time payment (not subscription-based)
- Includes lifetime updates
- Valid for a single Magento instance
- Additional extensions (like Hyvä Checkout) may have separate pricing
This pricing makes Hyvä a cost-effective alternative compared to long-term frontend development costs.
The company behind Hyvä focuses on simplifying Magento frontend development.
Core activities:
- Developing the Hyvä Theme for Magento 2
- Providing performance-first frontend solutions
- Supporting developers with documentation and tooling
- Building an ecosystem of compatible extensions
Hyvä’s goal is to reduce complexity and improve performance in Magento stores, which traditionally suffer from slow frontend rendering.
Hyvä Theme improves Magento 2 speed, simplifies development, and enhances Core Web Vitals by reducing JavaScript and using modern frontend tools.
