CSS et JavaScript personnalises dans PrestaShop sans casser les mises a jour

Vous voulez changer la couleur d'un bouton. Vous ouvrez les fichiers de votre thème PrestaShop, trouvez le CSS, le modifiez et le bouton a exactement l'apparence que vous souhaitez. Deux semaines plus tard, vous mettez à jour le thème et votre modification a disparu. C'est l'erreur la plus courante dans la personnalisation PrestaShop, et elle est entièrement évitable. Ce guide couvre chaque méthode sûre pour ajouter du CSS et du JavaScript personnalisés à votre boutique PrestaShop — des petits ajustements d'une ligne aux fonctionnalités complexes — sans aucun risque de perdre votre travail lors de la mise à jour du thème, du cœur de PrestaShop ou des modules.

Pourquoi éditer directement les fichiers du thème est dangereux

Les thèmes PrestaShop sont composés de templates Smarty (fichiers .tpl), de feuilles de style CSS et de fichiers JavaScript organisés dans le répertoire /themes/votre-theme/. Quand vous mettez à jour un thème, le processus de mise à jour remplace ces fichiers par la nouvelle version. Toute modification directe que vous avez faite aux fichiers originaux du thème est écrasée sans avertissement.

La même chose s'applique aux fichiers des modules dans /modules/nom-du-module/views/. Les mises à jour de modules remplacent ces répertoires entièrement.

Il existe exactement cinq méthodes sûres pour ajouter du CSS et du JavaScript personnalisés à PrestaShop :

Méthode 1 : Le fichier custom.css (la plus simple)

La plupart des thèmes PrestaShop modernes supportent un fichier custom.css. Ce fichier est chargé après toutes les autres feuilles de style du thème, donc vos règles prennent la priorité. L'avantage clé : les mises à jour du thème n'écrasent pas ce fichier car il ne fait pas partie de la distribution du thème.

Pour l'utiliser, créez (ou éditez) le fichier à :

/themes/votre-theme/assets/css/custom.css

Ajoutez vos règles CSS. Elles seront chargées sur chaque page. Par exemple :

.btn-primary { background-color: #2c3e50; border-color: #2c3e50; }

Consultez la documentation de votre thème pour confirmer le chemin exact — certains thèmes utilisent /themes/votre-theme/css/custom.css à la place. Le thème Hummingbird (thème par défaut de PrestaShop 8) et le thème Classic supportent tous deux custom.css dans leurs répertoires d'assets.

Limitations de cette approche :

• Pas de JavaScript — c'est uniquement du CSS
• Votre CSS personnalisé est chargé sur chaque page, même là où il n'est pas nécessaire
• Vous ne pouvez pas charger conditionnellement des styles selon le type de page, le groupe client ou d'autres critères
• Certains thèmes ne supportent pas custom.css du tout — vous devez vérifier

Méthode 2 : Thème enfant (idéal pour les personnalisations lourdes)

Un thème enfant hérite de tout ce que contient un thème parent mais vous permet de surcharger des templates et feuilles de style spécifiques. Les mises à jour du thème parent n'affectent pas les surcharges de votre thème enfant.

Pour créer un thème enfant :

• Créez un nouveau répertoire : /themes/votre-theme-enfant/
• Créez un fichier config/theme.yml qui référence le thème parent
• Copiez uniquement les fichiers que vous souhaitez surcharger dans le répertoire du thème enfant

Le theme.yml doit contenir :

parent: votre-theme-parent
name: votre-theme-enfant
display_name: Mon thème personnalisé

Avec un thème enfant, vous pouvez ajouter un fichier custom.css, surcharger des templates spécifiques et ajouter des fichiers JavaScript personnalisés. Quand le thème parent est mis à jour, votre thème enfant conserve toutes ses surcharges.

C'est l'approche recommandée si vous prévoyez de faire plus de 5 à 10 modifications CSS. L'effort initial de création d'un thème enfant se rentabilise immédiatement en économies de maintenance.

Méthode 3 : Module de blocs HTML (idéal pour les non-développeurs)

Si vous n'êtes pas à l'aise avec l'édition de fichiers sur le serveur, un module de blocs HTML vous permet d'injecter du HTML, CSS et JavaScript personnalisés directement depuis le back-office. C'est l'approche la plus conviviale.

Le module mprhtmlblocks de mypresta.rocks est conçu spécifiquement à cet effet. Il vous permet de créer des blocs de code personnalisé et de les assigner à des hooks spécifiques (positions sur la page). Vous pouvez injecter du CSS dans la section <head>, du JavaScript avant la balise fermante </body>, ou du contenu HTML partout où un hook existe.

Avantages clés de l'approche par module :

• Pas d'accès fichier nécessaire : Tout est configuré dans le back-office
• Affichage conditionnel : Affichez les blocs uniquement sur des pages, catégories ou groupes clients spécifiques
• Support multi-boutique : Du code personnalisé différent pour différentes boutiques
• Contrôle de version : Les modifications sont stockées en base de données, les rendant indépendantes des mises à jour du thème et du cœur
• Retour en arrière facile : Désactivez un bloc pour retirer son effet sans supprimer le code

Les cas d'usage typiques pour les blocs HTML incluent l'ajout de scripts de suivi (Google Analytics, Facebook Pixel), l'injection de CSS personnalisé pour un style saisonnier, l'ajout de bannières promotionnelles et l'intégration de widgets tiers.

Méthode 4 : Module personnalisé avec addCSS/addJS (idéal pour les développeurs)

Si vous êtes développeur, l'approche la plus propre est de créer un petit module qui enregistre le CSS et le JavaScript via le système de gestion des assets de PrestaShop. Cette méthode est indépendante du thème et survit à toute mise à jour.

Créez un module avec une méthode hookActionFrontControllerSetMedia() :

public function hookActionFrontControllerSetMedia() {
  $this->context->controller->registerStylesheet('my-custom-css', 'modules/'.$this->name.'/views/css/custom.css', ['media' => 'all', 'priority' => 200]);
  $this->context->controller->registerJavascript('my-custom-js', 'modules/'.$this->name.'/views/js/custom.js', ['position' => 'bottom', 'priority' => 200]);
}

Dans PrestaShop 1.7+, utilisez registerStylesheet() et registerJavascript() au lieu des anciennes méthodes addCSS() et addJS(). Les nouvelles méthodes supportent l'ordonnancement par priorité, les media queries et les attributs de chargement async/defer.

Important : le bug addCSS avec query string

Il existe un problème connu dans PrestaShop où addCSS() avec un paramètre de query string (comme ?v=1.2.3) peut empêcher le chargement de la feuille de style. Si vous utilisez des query strings pour le cache-busting, utilisez registerStylesheet() à la place, qui gère cela correctement. C'est un bug subtil qui a piégé de nombreux développeurs — la feuille de style apparaît dans le code source HTML mais le navigateur ne l'applique pas car PrestaShop génère un chemin incorrect.

Chargement conditionnel

Vous pouvez charger conditionnellement du CSS et du JavaScript en fonction du contrôleur utilisé :

public function hookActionFrontControllerSetMedia() {
  $controller = $this->context->controller;
  if ($controller instanceof ProductController) {
    $this->context->controller->registerStylesheet('product-custom', ...);
  }
  if ($controller instanceof OrderController) {
    $this->context->controller->registerJavascript('checkout-custom', ...);
  }
}

Cela garantit que votre code personnalisé ne se charge que là où il est nécessaire, améliorant les performances de chargement des pages.

Méthode 5 : Module de personnalisation du thème (spécifique au thème)

Certains thèmes incluent leur propre module de personnalisation. Par exemple, le thème Warehouse a iqitthemeeditor avec un champ CSS personnalisé dans le back-office. Le thème Flavor et de nombreux thèmes commerciaux offrent une fonctionnalité similaire.

Si votre thème dispose d'un tel module, utilisez-le — le CSS personnalisé que vous y saisissez est conçu pour survivre aux mises à jour du thème. Cependant, sachez que changer de thème entraînera la perte de cette personnalisation.

JavaScript — Considérations particulières

Ajouter du JavaScript à PrestaShop nécessite plus de précautions que le CSS à cause des conflits potentiels avec le JavaScript existant du thème et la version de jQuery.

Disponibilité de jQuery

PrestaShop 1.7+ utilise jQuery 3.x en front-office. Si votre JavaScript personnalisé dépend de jQuery, assurez-vous que votre script se charge après jQuery en définissant un numéro de priorité élevé (plus élevé = se charge plus tard) dans registerJavascript().

Dans le back-office, PrestaShop utilise jQuery 1.x (dans les versions anciennes) ou 3.x (dans les versions récentes). Si vous écrivez du JavaScript côté admin, vérifiez d'abord la version de jQuery dans le code source de la page.

Évitez les scripts en ligne

N'ajoutez jamais de JavaScript directement dans les templates Smarty avec des balises <script>. Cela contourne la gestion des assets de PrestaShop, casse l'optimisation CCC (Combiner, Compresser, Mettre en cache) et crée des violations CSP (Content Security Policy). Utilisez toujours des fichiers .js externes chargés via les hooks appropriés.

JavaScript moderne (ES6+)

Si vous souhaitez utiliser des fonctionnalités JavaScript modernes (fonctions fléchées, async/await, modules), vous devez considérer la compatibilité navigateur. Les exigences minimales de navigateur de PrestaShop varient selon la version, mais le support d'IE11 n'a été abandonné que dans PrestaShop 8. Si vous supportez PrestaShop 1.7, vous devrez peut-être transpiler votre JavaScript avec Babel.

CSS : Spécificité et surcharge

Quand votre CSS personnalisé ne semble pas fonctionner, c'est presque toujours un problème de spécificité. Les sélecteurs CSS du thème sont plus spécifiques que les vôtres, donc le navigateur les applique à la place.

Solutions (par ordre de préférence) :

• Égaler la spécificité : Utilisez les outils de développement de votre navigateur pour trouver le sélecteur exact utilisé par le thème, et utilisez le même sélecteur ou un plus spécifique dans votre CSS personnalisé.
• Augmenter la spécificité : Ajoutez un élément parent à votre sélecteur. Au lieu de .btn-primary, utilisez body .btn-primary ou #wrapper .btn-primary.
• Utiliser !important : En dernier recours uniquement. L'abus de !important crée une course à la spécificité qui rend la maintenance future pénible.

Tests et débogage

Après avoir ajouté du CSS ou JavaScript personnalisé, vérifiez que cela fonctionne correctement :

• Videz le cache : PrestaShop met en cache le CSS et JS de manière agressive. Allez dans Paramètres avancés > Performance et cliquez sur « Vider le cache » après chaque modification. En développement, définissez « Forcer la compilation » sur Oui pour les templates Smarty.
• Vérifiez CCC : Si CCC (Combiner, Compresser, Mettre en cache) est activé, vos fichiers CSS/JS individuels sont combinés en un seul fichier. Cela peut causer des problèmes d'ordre de chargement. Désactivez temporairement CCC pour isoler les problèmes.
• Outils de développement du navigateur : Utilisez l'onglet Réseau pour vérifier que vos fichiers CSS/JS se chargent (statut 200, pas 404). Utilisez l'onglet Éléments pour vérifier que vos règles CSS sont appliquées (pas barrées par des règles de spécificité supérieure).
• Cache CDN : Si vous utilisez Cloudflare ou un autre CDN, purgez le cache CDN après les modifications CSS/JS. Cela résout de nombreuses situations « j'ai changé mais rien ne s'est passé ».

Résumé des bonnes pratiques

• N'éditez jamais directement les fichiers du thème — utilisez custom.css, les thèmes enfants ou les modules
• Pour 1 à 5 petites modifications CSS : utilisez custom.css
• Pour des changements visuels importants : créez un thème enfant
• Pour les utilisateurs non techniques : utilisez un module de blocs HTML comme mprhtmlblocks
• Pour les développeurs : créez un petit module avec registerStylesheet/registerJavascript
• Chargez toujours le JavaScript en bas de page (position: bottom)
• Videz tous les caches après avoir fait des modifications
• Gardez une sauvegarde de vos personnalisations en dehors du répertoire du thème

Le CSS et JavaScript personnalisés sont ce qui fait d'une boutique PrestaShop la vôtre, sans être lié à une version spécifique du thème. Faites-le bien dès le départ et vous économiserez d'innombrables heures à ré-appliquer des modifications perdues. Pour un moyen facile de gérer des blocs de code personnalisé à travers votre boutique PrestaShop, consultez le module mprhtmlblocks chez mypresta.rocks — il vous permet d'injecter et gérer du HTML, CSS et JavaScript depuis le back-office sans toucher un seul fichier sur votre serveur.

Articles Connexes

• Thèmes Enfants dans PrestaShop : Pourquoi ne Jamais Modifier le Thème Parent
• Les Overrides dans PrestaShop : Quand Ils Aident et Quand Ils Cassent Tout
• Comment choisir le bon thème PrestaShop pour votre activité