Development Guidelines
Note
This guide is for creating new Compatibility Modules from scratch.
For making existing modules Hyvä-compatible
To make an *existing* module Hyvä-compatible without creating a new compatibility module, refer to the Making Existing Modules Hyvä-Compatible section in our Getting Started documentation.
Where to Begin Coding
This guide outlines the process for creating a new Compatibility Module. We assume you have an empty compatibility module already installed in your development environment.
The exact steps for creating a compatibility module vary based on the original module. This guide provides a general overview that you can adapt.
- Identify a page that uses functionality from the original module.
- Open this page in a private browser window using a Luma theme store view (for reference).
- Open the *same* page in your Hyvä theme store view.
- In the Hyvä store view, open the browser console and check for errors (e.g.,
require is not defined). - Pinpoint the original module's template responsible for the error-causing feature.
- Copy this template to the *same relative path* within your compatibility module's
view/frontend/templatesdirectory. - Open the copied template in your IDE.
- Refactor the template: Inline JavaScript, convert it to vanilla JS and Alpine.js, and style components with Tailwind CSS. Detailed instructions are in the "From Luma to Hyvä" section.
- Once the template renders correctly and the feature works, clean up the code and proceed to the next template.
Tip
If multiple templates on a page cause errors, copy them all to your compatibility module. Then, short-circuit them with an early <?php return; ?> to address them one by one.
Important
Always work incrementally: tackle one small step at a time instead of everything at once.
Naming Conventions
Magento Module
Compatibility module names use the Hyva namespace, followed by the original module's namespace and name.
- Original:
Smile_ElasticSuite - Compat Module:
Hyva_SmileElasticSuite
Composer Package
The composer vendor name is hyva-themes. The full package name follows the format: hyva-themes/magento2-<original-module>.
- Original:
smile/magento-elasticsuite - Compat Module:
hyva-themes/magento2-smile-elasticsuite
Other Vendor Names
This naming convention applies to packages hosted on gitlab.hyva.io under the hyva-themes vendor. For compatibility modules in external repositories (e.g., GitHub), use a different vendor name and include hyva in the package name. For instance, my-org/magento-integration would become my-org/magento-hyva-integration.
Folder Structure
Hyvä and compatibility modules share a standard folder structure and minimal file set. New Compatibility Module repositories already include the basic structure, LICENSE.md, and README.md.
magento2-example-module/
├── LICENSE.md
├── README.md
├── composer.json
└── src
├── etc
│ ├── frontend
│ │ └── di.xml
│ └── module.xml
└── registration.php
Place tests in a tests/ directory at the same level as src/. The LICENSE.md file is a copy of the Hyvä Themes Software User License and *must not be altered*. The README.md should contain basic information about the original module, plus any additional details needed for the compatibility module.
Coding Standards
Hyvä adheres to the Magento 2 coding standard. All contributions and compatibility modules *must* follow this, including using tools like PHP CodeSniffer (phpcs) and PHP Mess Detector (phpmd).
If a rule is inappropriate for a specific circumstance, you may disable it using the relevant annotation (e.g., // phpcs:disable Generic.Files.LineLength.TooLong). Always be as specific as possible when disabling rules.
Template PHPDoc Variable Annotations
Annotate all values assigned to a template block at the top of the template file, if used. Importing class names improves code readability.
<?php
declare(strict_types=1);
use Hyva\Theme\Model\ViewModelRegistry;
use Magento\Framework\Escaper;
use Magento\Framework\View\Element\Template;
/** @var Template $block */
/** @var Escaper $escaper */
/** @var ViewModelRegistry $viewModels */
Copyright Annotations
Unsure which copyright notice to use for your compatibility module?
- Similar Code: If a file closely resembles one in Hyvä core, retain the Hyvä copyright notice.
- Unique Code: For files created from scratch, you may use either the Hyvä copyright notice or your own. If using your own, *always* include a line permitting its use with Hyvä installations.