Table of Contents & Menu

Navigation

Getting Started with Compatibility Modules

This guide covers how to make Magento modules Hyvä-compatible and contribute them to the compatibility module pool.

Prerequisites

To follow this guide, you should be familiar with:

Magento 2 frontend development
PHP
JavaScript
git
Hyvä Theme installation and setup
Alpine.js basics
Tailwind CSS basics

Also, review the general Hyvä Theme development documentation, as its principles apply to compatibility modules.

Useful Tools & Tips

These tools and tips will help you work more efficiently.

Set up a Luma reference store view

Run a Luma theme store view alongside your Hyvä store view. This allows you to compare module behavior in Luma while developing for Hyvä.

Install IDE Plugins and Extensions

We recommend installing these helpful utilities:

Alpine.js devtools extension for Chrome or Firefox
Alpine.js Support and Tailwind CSS PHPStorm plugins
Alpine.js and Tailwind CSS IntelliSense VSCode extensions (if you use VS code)

Commercial Tools

Windy extension for Chrome and Firefox
DevTools for Tailwind extension for Chrome

Contribution Process Overview

You can contribute to:

Compatibility Modules (commercial Hyvä license required for access on gitlab.hyva.io)
Hyvä React Checkout (open-source license, free on github.com)
Hyvä Admin (open-source license, free on github.com)

This guide focuses on Compatibility Modules. Open-source projects (Hyvä React Checkout, Hyvä Admin) follow standard GitHub contribution processes and are not covered here. For Hyvä core contributions, see the Hyvä contribution guidelines.

Throughout this document, GitLab refers to gitlab.hyva.io.

If you encounter any issues, please ask for help in Slack. We're here to assist!

Step-by-step contribution process:

To contribute a new Compatibility Module, notify a Hyvä team member. They will create a skeleton repository for you in the Hyvä Compat group on GitLab and provide the link. You will have write privileges to this repository.
If no ticket exists for the module in the Compatibility Module Tracker, create a new issue using the “Module Request” template. Inform the Hyvä team so they can add the “In Progress” label.
Clone the repository to your development environment.
Create a git branch for your changes.
Develop your code.
Commit changes. Repeat step 5 until development is complete.
Push changes to a new branch on GitLab and create a merge request.
As the maintainer, you can merge your feature branch directly into main once ready. Code reviews from your team or the Hyvä team (via Slack) are optional for compatibility modules.
Once the module is complete, add a 1.0.0 tag to enable installation via packagist.com. Notify the Hyvä team to update the module's label to “Published” in the Compat Module Tracker.

Cloning the Repository

You can work on Magento modules in your development environment using one of three main approaches:

Clone the module into app/code
Add the repository as a composer git source and install the module into vendor with composer require --prefer-source
Clone the repository to a local directory (e.g., local-src/), add that folder as a path repository to the Magento composer.json file, and install the module with composer.

All approaches are valid, but we recommend the third option.

Setting up a local path composer repository

Follow these steps to set up a local path Composer repository in your development environment.

Create a directory for your local code, e.g., local-src/, within your Magento base directory.
```
mkdir local-src
```

Clone the Compatibility Module repository into this directory.

cd local-src
git clone [email protected]:hyva-themes/hyva-compat/magento2-your-module.git
cd ..

Add the local-src subdirectories as a Composer path repository. Then, move the local-src repository to the top of the repositories list in your root composer.json to ensure it takes precedence:

composer config repositories.local-src path 'local-src/*'

Then open your root composer.json file and move the local-src repository to the top of the repository list, so it takes precedence over any remote repositories:

"repositories": {
    "local-src": {
        "type": "path",
        "url": "local-src/*"
    },
    "private-packagist": {
        "type": "composer",
        "url": "https://hyva-themes.repo.packagist.com/CUSTOMERNAME/"
    },
    "0": {
        "type": "composer",
        "url": "https://repo.magento.com/"
    }
}

Install the module using Composer. This creates a symlink from local-src/magento2-your-module to vendor/hyva-themes/magento2-your-module. If you encounter a minimum-stability error, specify the branch (e.g., composer require hyva-themes/magento2-your-module:dev-main).
```
composer require hyva-themes/magento2-your-module
```
If you get an error that the package does not match the configured minimum-stability, tell composer what branch to install by adding the :dev-[BRANCH] suffix, e.g. composer require hyva-themes/magento2-your-module:dev-main.
Exclude one of the directories from your IDE index to prevent confusion. In PHPStorm, right-click the local-src folder and select Mark Directory as > Excluded. Then, remove the exclusion for vendor/hyva-themes/magento2-your-module in PHPStorm Settings > Directories.

Troubleshooting Composer Path Repositories

If using the path Composer repository, you might encounter an error indicating the package exists in multiple repositories with different priorities. This often happens in virtualized environments (e.g., Warden) where the .git directory isn't synchronized into the container, preventing Composer from determining the package version.

There are a number of possible solutions:

Clone the repository inside the container instead of on the host system.

Add the package version to the local-src repository configuration in your root composer.json:

{
    "type": "path",
    "url": "local-src/*",
    "options": {
        "versions": {
            "hyva-themes/your-module": "dev-main"
        }
    }
}

Alternatively, add "version": "dev-main" to the package's composer.json file. Not recommended due to potential inconsistencies.

Making Existing Modules Hyvä-Compatible

Making an existing module Hyvä-compatible is similar to creating a new compatibility module. The key difference is manually registering your module for inclusion in hyva-themes.json. This process, detailed in Registering a module for inclusion in hyva-themes.json, enables your theme to scan and import necessary CSS.

Otherwise, follow the same steps, ensuring your phtml, CSS, and JavaScript code is compatible with both Luma and Hyvä themes.

For Hyvä-specific phtml and JavaScript, use layout XML files with the hyva_ prefix. This ensures Luma themes ignore these layouts, making them exclusive to Hyvä, as explained in The hyva_ Layout Handles documentation.

On this page