Documentation

Installation guide

From purchase to an active extension on your Hyvä store in ten minutes: access key, private Composer repository, installation, Tailwind build and updates.

Requirements

Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9 (2.4.8 or later for the themes and AJAX Add to Cart);
a Hyvä 1.3 to 1.5 theme: Hyvä Default, Hyvä CSP or a child theme;
PHP 8.2 to 8.5 and Composer 2;
SSH access to the installation, and Node.js 20 or later to build the styles of your theme.

Always install and test on your development or staging environment before production: your licence covers them.

1. Create an access key

After payment, your extensions appear in My account › My licences. Then open My account › Composer access and create a key, for example "Production" or "CI".

Copy the secret right away: it is shown only once and we only keep a hash of it. Create one key per environment or tool: you can revoke one without blocking the others.

2. Add the Mokadev repository

At the root of your Magento project, add the private Mokadev repository. It only contains the extensions of your licences, and the versions released during your update period.

composer config repositories.mokadev composer https://shop.mokadev.com/en/composer/

The "Composer access" page shows this command and the next ones, ready to copy with your key.

3. Save your credentials

The public key is the username and the secret is the password:

composer config --auth http-basic.shop.mokadev.com <public-key> <secret>

Composer saves them in the auth.json file of the project, in this form:

{
    "http-basic": {
        "shop.mokadev.com": {
            "username": "<public-key>",
            "password": "<secret>"
        }
    }
}

Do not commit auth.json (add it to your .gitignore). In continuous integration, pass the credentials in the COMPOSER_AUTH environment variable with the same JSON content.

4. Install the extension

The package name is listed in the documentation and in "My licences":

composer require mokadev/module-free-shipping-bar
bin/magento setup:upgrade

In production mode, then compile the code and deploy the static files:

bin/magento setup:di:compile
bin/magento setup:static-content:deploy en_US fr_FR

5. Rebuild the styles of your Hyvä theme

Our extensions do not add a stylesheet: their Tailwind classes are compiled with those of your theme, into a single optimised CSS file. Register them, then run the build again:

bin/magento hyva:config:generate
cd app/design/frontend/<Vendor>/<theme>/web/tailwind
npm ci
npm run build

With Hyvä 1.3 (Tailwind v3), the build command is npm run build-prod. Finally, flush the cache: bin/magento cache:flush.

6. Configure

The settings of each extension are in Stores › Configuration › Mokadev, and can be set per website and per store view. The section of each extension in the documentation links to its product page, which details its features; the README.md file shipped with the package describes every setting and the customisation options.

Installing a Mokadev theme

composer require mokadev/theme-hyva-furniture
bin/magento setup:upgrade

Assign the theme in Content › Design › Configuration, then build its styles:

cd vendor/mokadev/theme-hyva-furniture/web/tailwind
npm ci
npm run build

To customise the theme, preferably create a child theme: texts, links and lists are layout arguments that you can change without copying templates.

Updating

composer update "mokadev/*"
bin/magento setup:upgrade

Then run the Tailwind build again (step 5). The changelog summarises the new features and fixes of each release. After your update period ends, Composer keeps installing the versions you already obtained, but no longer offers the next ones.

Renewing the update period

From My licences, the "Renew for 1 year" button adds the renewal to the cart:

50% of the extension price when your last purchase or renewal is less than a year old;
full price otherwise.

The new period starts at the end of the current one: renewing early does not make you lose a single day. New versions are available in Composer as soon as the payment is confirmed.

Troubleshooting

Composer answers 401 or 403: The key is wrong, revoked, or saved for another domain. Check the domain used in auth.json (the same as the repository's) or create a new key.
"Could not find a matching version of package": The package is not covered by one of your licences, or the requested version was released after the end of your update period. Check "My licences", then run composer clear-cache after a renewal.
The extension is displayed without styles: Its classes were not compiled: run bin/magento hyva:config:generate and the Tailwind build of your theme again, then deploy the new CSS file.
A JavaScript error appears with a Hyvä CSP theme: Our Alpine.js components are CSP compatible. Make sure the full page cache was flushed after the installation, then write to us with the console message.

Still stuck? See the Support page: we answer within one business day.

Cookie	Provider	Purpose	Duration
PHPSESSID	This store	Keeps your session (cart, login).	Session
form_key	This store	Protects forms against CSRF attacks.	1 year
mage-cache-sessid, mage-cache-storage, private_content_version, section_data_ids	This store	Cart, customer data and page cache.	1 year
X-Magento-Vary	This store	Serves the right cached page version.	Session
mokadev_consent	This store	Remembers your cookie choices.	6 months