Pourquoi mon mini-panier WooCommerce cesse-t-il de s'afficher quand j'active « Remove Unused CSS » ?

Vous optimisez la boutique, le rapport PageSpeed s'améliore, et quelques heures plus tard un client vous écrit : l'icône du panier ne fait rien. Il la survole, rien ne s'ouvre. Ou elle s'ouvre vide, ou sans aucun style. Vous n'avez jamais touché au panier. Vous avez activé une optimisation CSS. Alors, que s'est-il passé ?

Le mini-panier, c'est la petite icône de panier dans votre en-tête, généralement accompagnée d'un compteur d'articles, et le panneau qui s'ouvre quand vous le survolez ou le touchez, listant le contenu du panier. C'est ce panneau qui casse, et il y a deux raisons à cela, souvent combinées.

Ce qu'est réellement un mini-panier (et pourquoi il est fragile)

Au chargement de la page, le panneau n'est pas censé être visible. Il reste masqué : display:none, ou opacity:0 avec visibility:hidden, ou repoussé hors écran. Rien ne s'affiche tant que vous n'interagissez pas.

Deux éléments le font apparaître. Le CSS porte son état masqué et son état ouvert, les règles qui le rendent visible et positionnent le panneau. Le JavaScript s'occupe du basculement : au survol ou au tap, il ajoute une classe qui active le panneau, ou il construit et injecte le contenu du panier à la volée. Sur WooCommerce, cette construction est généralement assurée par wc-cart-fragments.js, le script qui garde le mini-panier et le compteur d'articles synchronisés via AJAX.

Retirez le bon CSS, ou empêchez le bon script de s'exécuter, et le panneau n'apparaît jamais. Les deux surviennent quand vous optimisez sans indiquer à l'outil de laisser le panier tranquille.

Cause 1 : le CSS est masqué, donc il est supprimé

Une passe de used-CSS ou de suppression du CSS inutilisé conserve les styles de ce qui est visible au moment du rendu de la page, et supprime le reste. Votre panneau de mini-panier est masqué à cet instant, donc l'outil juge ses styles superflus et les retire.

Deux choses cassent en conséquence. La règle qui faisait apparaître le panneau à l'ouverture a disparu, donc le survol ne produit rien de visible. Ou bien le style propre du panneau a disparu, donc il s'ouvre sans mise en forme : une simple liste sans positionnement ni arrière-plan, qui déborde dans la page.

C'est le même mécanisme qui supprime un menu mobile masqué ou un overlay de recherche. L'explication complète, et la correction durable, se trouvent dans notre guide sur le Critical CSS qui casse les menus et les overlays.

Key infos

Le panneau est masqué au chargement, donc une passe de used-CSS juge ses styles inutiles et les supprime.
Vous perdez l'état ouvert (rien n'apparaît) ou le style du panneau (il s'ouvre cassé).
Même cause qu'un menu mobile ou un overlay de recherche supprimé.

Cause 2 : le JavaScript ne se déclenche jamais

Même avec les styles intacts, le panneau a besoin de son script pour s'ouvrir. Si vous retardez ou différez le JavaScript, le script qui ajoute la classe d'ouverture, ou celui qui construit le panier, peut ne pas être là quand le visiteur survole l'icône.

Sur WooCommerce, le suspect habituel est wc-cart-fragments.js, plus le script du thème ou du panier latéral qui gère le survol, plus jQuery en dessous. Retardez la chaîne et le compteur cesse de se mettre à jour, ou le panneau reste vide, ou l'icône est tout simplement morte.

Différer le JavaScript vaut la peine, mais l'interaction du panier doit continuer à fonctionner. La méthode, qui consiste à exclure toute la chaîne de dépendances par fragment d'URL avec une garde pour qu'elle tolère un chargement précoce, est la même que celle qui corrige un menu burger à double tap, traitée dans le guide sur le menu burger.

Une précaution : ne désactivez pas wc-cart-fragments.js pour économiser la requête AJAX. Cette requête a un coût réel sur chaque page, et vous pouvez limiter où elle s'exécute, mais la supprimer tue un mini-panier vivant. Excluez-la du délai, ne la supprimez pas.

Key infos

Le panneau a besoin d'un script pour s'ouvrir ; un délai JS peut empêcher ce script de s'exécuter à temps.
Sur WooCommerce, c'est généralement wc-cart-fragments.js plus le script du thème ou du panier latéral plus jQuery.
Excluez cart fragments du délai, ne le supprimez jamais, sinon le panier en direct cesse de se mettre à jour.

Diagnostiquer en 30 secondes

Désactivez un instant l'option used-CSS. Si le mini-panier refonctionne, le CSS est le coupable. Réactivez-la et passez directement à la safelist.

Si les styles sont clairement présents mais que le panneau refuse toujours de s'ouvrir, surveillez l'onglet Network : survolez l'icône et vérifiez si wc-cart-fragments.js et le script du thème se chargent et s'exécutent. S'ils se déclenchent en retard, ou pas du tout, le délai est le coupable.

Et vérifiez à la fois sur mobile et sur desktop. De nombreux moteurs conservent une version optimisée distincte par appareil, donc un panier qui fonctionne sur desktop peut rester cassé sur mobile.

Les exceptions à ajouter

Conserver le CSS (safelist). Protégez les sélecteurs du mini-panier de l'élagage. Les plus courants sur WooCommerce :

le widget natif : .widget_shopping_cart, .widget_shopping_cart_content, .woocommerce-mini-cart, .mini_cart_item, .cart_list, .cart-contents
le panier en blocs, si vous l'utilisez : .wc-block-mini-cart et ses enfants
l'état ouvert, le plus important : la classe qui rend le panneau visible sur votre site (souvent .active, .is-open, .open, .show)
le conteneur de votre thème ou de votre extension de panier latéral, que vous devrez repérer directement sur la page

Une safelist dépend du plugin et de la configuration, donc elle dérive avec le temps. La version qui survit à une régénération consiste à inliner l'état masqué et le style d'ouverture complet dans un bloc que l'optimiseur est chargé de laisser tranquille, placé après wp_head(). Cette méthode est décrite dans le guide sur le Critical CSS.

Conserver le JS (exclusions). Sortez les scripts du panier du délai, en tant que chaîne :

wc-cart-fragments.js, celui qui construit et met à jour le mini-panier
jQuery et jQuery Migrate, dont il dépend
le script de votre thème ou de votre extension de panier latéral qui gère le survol ou le basculement

Ciblez-les par un fragment unique de leur URL, pas par le handle interne, et assurez-vous que le script exclu tolère un chargement précoce. Excluez toute la chaîne ensemble, sinon vous obtenez le résultat « exclu mais mort » : le panier est listé comme exclu et ne fonctionne toujours pas.

Key infos

Mettez en safelist les sélecteurs du mini-panier, et surtout la classe qui ouvre le panneau.
Mieux encore, inlinez les styles masqué et ouvert dans un bloc non optimisable, pour qu'il survive à une régénération.
Sortez la chaîne JS du délai : cart fragments, jQuery, et le script du thème ou du panier latéral, par URL.

Une note pour les créateurs de thèmes et d'extensions

Si vous construisez le panier, vous pouvez réduire tout cela à une exception d'une seule ligne. Donnez au composant une seule classe d'espace de noms, disons minicart, et cantonnez toutes les règles sous elle : l'état masqué, l'état ouvert, et chaque enfant.

CSS

.minicart              { opacity: 0; visibility: hidden; }
.minicart.is-open      { opacity: 1; visibility: visible; }
.minicart .item        { /* ... */ }
.minicart .count       { /* ... */ }

Maintenant, tout le composant est mis en safelist avec un seul token, .minicart, et aucun optimiseur ne peut le démembrer. Éparpillez les mêmes styles sur des sélecteurs génériques comme .cart-item ou .flyout.open et chacun a besoin de sa propre entrée de safelist, ce qui casse dès qu'on en oublie une. Cela aide n'importe quel optimiseur, pas seulement Mantys.

Avec Mantys Core

Mantys Core peut piloter toute votre couche de performance, cache inclus, ou cohabiter avec votre installation existante. Sur une boutique, le mini-panier est exactement le genre d'élément qu'il est conçu pour protéger.

il respecte les blocs que vous marquez comme non optimisables, donc les styles masqué et ouvert du panier survivent ;
il conserve les exceptions JavaScript déclarées par fragment d'URL avec une garde d'état, donc cart fragments et le script de survol continuent de fonctionner pendant que le reste est différé ;
il régénère le CSS page par page, donc vos templates de boutique ne sont pas élagués comme une simple landing page ;
et il gère mobile et desktop séparément, donc un panier qui fonctionne sur l'un n'est pas cassé sur l'autre.

Vous gardez la boutique fonctionnelle pendant que le poids s'allège, sans avoir à surveiller une safelist.

En résumé

Le mini-panier est masqué jusqu'à ce qu'on le survole, donc une passe de used-CSS supprime ses styles et un délai JS l'empêche de s'ouvrir.
La première cause est le CSS : le panneau masqué est jugé inutile et supprimé. La seconde cause est le JS : le script qui ouvre ou construit le panier ne s'exécute jamais.
Corrigez le CSS avec une safelist, ou mieux, un bloc inline non optimisable pour les styles masqué et ouvert.
Corrigez le JS en excluant toute la chaîne, cart fragments plus jQuery plus le script du thème, du délai, et ne supprimez jamais cart fragments.
Si vous construisez le thème, placez le panier sous une seule classe d'espace de noms pour que l'exception tienne en une ligne.