Documentation

Guide d'installation

De l'achat à l'extension active sur votre boutique Hyvä, en dix minutes : clé d'accès, dépôt Composer privé, installation, build Tailwind et mises à jour.

Prérequis

Magento Open Source ou Adobe Commerce 2.4.6 à 2.4.9 (2.4.8 minimum pour les thèmes et AJAX Add to Cart) ;
un thème Hyvä 1.3 à 1.5 : Hyvä Default, Hyvä CSP ou un thème enfant ;
PHP 8.2 à 8.5 et Composer 2 ;
un accès SSH à l'installation, et Node.js 20 ou plus pour compiler les styles de votre thème.

Installez et testez toujours sur votre environnement de développement ou de préproduction avant la production : votre licence les couvre.

1. Créer une clé d'accès

Après le paiement, vos extensions apparaissent dans Mon compte › Mes licences. Ouvrez ensuite Mon compte › Accès Composer et créez une clé, par exemple « Production » ou « CI ».

Copiez le secret immédiatement : il n'est affiché qu'une seule fois et nous n'en conservons qu'une empreinte. Créez une clé par environnement ou par outil : vous pourrez en révoquer une sans bloquer les autres.

2. Déclarer le dépôt Mokadev

À la racine de votre projet Magento, ajoutez le dépôt privé Mokadev. Il ne contient que les extensions de vos licences, et les versions publiées pendant votre période de mises à jour.

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

La page « Accès Composer » affiche cette commande et les suivantes, prêtes à copier avec votre clé.

3. Enregistrer vos identifiants

La clé publique sert d'identifiant et le secret de mot de passe :

composer config --auth http-basic.shop.mokadev.com <clé-publique> <secret>

Composer les enregistre dans le fichier auth.json du projet, sous cette forme :

{
    "http-basic": {
        "shop.mokadev.com": {
            "username": "<clé-publique>",
            "password": "<secret>"
        }
    }
}

Ne versionnez pas auth.json (ajoutez-le à votre .gitignore). En intégration continue, passez les identifiants dans la variable d'environnement COMPOSER_AUTH avec le même contenu JSON.

4. Installer l'extension

Le nom du paquet figure dans la documentation et dans « Mes licences » :

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

En mode production, compilez ensuite le code et déployez les fichiers statiques :

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

5. Recompiler les styles de votre thème Hyvä

Nos extensions n'ajoutent pas de feuille de style : leurs classes Tailwind sont compilées avec celles de votre thème, pour un seul fichier CSS optimisé. Déclarez-les puis relancez le build :

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

Avec Hyvä 1.3 (Tailwind v3), la commande de build est npm run build-prod. Videz enfin le cache : bin/magento cache:flush.

6. Configurer

Les réglages de chaque extension se trouvent dans Magasins › Configuration › Mokadev, et peuvent être définis par site et par vue magasin. La section de chaque extension de la documentation renvoie à sa fiche produit, qui détaille ses fonctionnalités ; le fichier README.md livré avec le paquet décrit chaque réglage et les possibilités de personnalisation.

Installer un thème Mokadev

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

Affectez le thème dans Contenu › Design › Configuration, puis compilez ses styles :

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

Pour personnaliser le thème, créez de préférence un thème enfant : les textes, liens et listes sont des arguments de layout, modifiables sans copier les templates.

Mettre à jour

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

Relancez ensuite le build Tailwind (étape 5). Le journal des versions résume les nouveautés et correctifs de chaque version. Après la fin de votre période de mises à jour, Composer continue d'installer les versions que vous avez déjà obtenues, mais ne propose plus les suivantes.

Renouveler la période de mises à jour

Depuis Mes licences, le bouton « Renouveler pour 1 an » ajoute le renouvellement au panier :

50 % du prix de l'extension si votre dernier achat ou renouvellement date de moins d'un an ;
prix plein au-delà.

La nouvelle période démarre à la fin de la période en cours : renouveler en avance ne vous fait perdre aucun jour. Les nouvelles versions sont disponibles dans Composer dès le paiement confirmé.

Dépannage

Composer répond 401 ou 403: La clé est incorrecte, révoquée, ou enregistrée pour un autre domaine. Vérifiez le domaine utilisé dans auth.json (identique à celui du dépôt) ou créez une nouvelle clé.
« Could not find a matching version of package »: Le paquet n'est pas couvert par une de vos licences, ou la version demandée a été publiée après la fin de votre période de mises à jour. Consultez « Mes licences », puis lancez composer clear-cache après un renouvellement.
L'extension s'affiche sans style: Les classes n'ont pas été compilées : relancez bin/magento hyva:config:generate puis le build Tailwind de votre thème, et déployez le nouveau fichier CSS.
Une erreur JavaScript apparaît avec un thème Hyvä CSP: Nos composants Alpine.js sont compatibles CSP. Vérifiez que le cache pleine page a été vidé après l'installation, puis écrivez-nous avec le message de la console.

Toujours bloqué ? Consultez la page Support : nous répondons sous un jour ouvré.

Cookie	Fournisseur	Finalité	Durée
PHPSESSID	Cette boutique	Conserve votre session (panier, connexion).	Session
form_key	Cette boutique	Protège les formulaires contre les attaques CSRF.	1 an
mage-cache-sessid, mage-cache-storage, private_content_version, section_data_ids	Cette boutique	Panier, données client et cache des pages.	1 an
X-Magento-Vary	Cette boutique	Sert la bonne version de la page en cache.	Session
mokadev_consent	Cette boutique	Mémorise vos choix de cookies.	6 mois