Conserver le thème et éviter le flash

Lorsqu'une page se charge, React doit télécharger, analyser et exécuter JavaScript avant de pouvoir lire localStorage et appliquer le thème correct. Pendant cet intervalle, le navigateur affiche les styles par défaut. Si l'utilisateur préfère le mode sombre alors que votre valeur par défaut est le mode clair, il voit un bref écran blanc avant la correction du thème.

La solution consiste à placer un script intégré directement dans l'document head, qui s'exécute de manière synchrone avant tout autre code. Ce script lit immédiatement localStorage et définit data-theme sur document.documentElement. Comme il bloque l'exécution, le navigateur applique l'attribut avant d'afficher le moindre contenu.

Les scripts asynchrones ou différés s'exécutent après l'analyse du HTML et potentiellement après le premier affichage. Cela annule entièrement l'objectif recherché. Le script intégré directement et bloquant ne doit avoir aucun attribut async ou defer et ne doit pas être chargé depuis un fichier externe. Il doit être très court afin de réduire au minimum le coût en performances.

Le script bloquant reste minimal : lisez localStorage.getItem('theme'), vérifiez window.matchMedia('(prefers-color-scheme: dark)').matches comme solution de repli, puis appelez document.documentElement.setAttribute('data-theme', theme). Entourez-le d'une gestion des exceptions au cas où localStorage ne serait pas disponible en navigation privée.

Dans Next.js, utilisez le composant Script de next/script avec strategy="beforeInteractive" dans _document.js. La stratégie beforeInteractive injecte le script dans le HTML de la page avant l'exécution de tout code JavaScript de la page, ce qui reproduit le comportement bloquant dans la chaîne de traitement de compilation Next.js.

Dans un projet Vite ou Create React App, modifiez directement index.html et placez la balise de script intégrée directement dans l'head, avant tout autre script. Comme index.html est le point d'entrée du navigateur, le script s'exécute avant le démarrage de React. Gardez-le concis pour rester sous la limite de 100 octets.

Dans une application générée côté serveur, le serveur peut lire le thème à partir d'un cookie envoyé avec la requête. Il définit ensuite data-theme dans le HTML généré avant de l'envoyer au navigateur. Cela évite entièrement l'affichage fugace côté client, car le thème correct se trouve dès le premier octet du HTML.

Le flux complet est le suivant : le navigateur télécharge le HTML, l'analyseur rencontre le script intégré bloquant, le script lit localStorage et définit data-theme, l'analyseur poursuit son travail, la page est affichée avec le thème correct, puis React s'hydrate et récupère le même thème depuis localStorage. L'utilisateur voit un thème cohérent dès le début.

Pour vérifier que la correction fonctionne, ouvrez Chrome DevTools, accédez à l'onglet Réseau et limitez la vitesse à 3G lente. Rechargez la page. Si vous voyez le thème changer pendant le chargement, l'affichage fugace n'est pas corrigé. Avec le script bloquant en place, le premier affichage doit déjà présenter le thème correct, même avec une connexion lente.

Si l'état initial de votre thème React prend par défaut la valeur claire alors que le script bloquant a défini la valeur sombre avant l'hydratation, React peut signaler une divergence lors de l'hydratation. Évitez ce problème en initialisant également l'état du thème React en lisant localStorage lors du rendu initial, afin que le HTML rendu par React corresponde à l'état du DOM défini par le script bloquant.

Storybook et les environnements de test ne chargent pas votre index.html ; le script bloquant ne s'y exécute donc jamais. Fournissez un décorateur ou une configuration de test qui applique un attribut data-theme par défaut dans ces environnements. Cela évite les incohérences visuelles déroutantes lors du développement isolé des composants.

Empêchez l'affichage fugace du mauvais thème en injectant dans l'en-tête du document un petit script intégré bloquant qui lit localStorage et définit data-theme avant tout affichage. Dans Next.js, utilisez strategy="beforeInteractive" ; dans Vite ou CRA, ajoutez-le directement à index.html. Les applications SSR peuvent lire un cookie pour définir le thème côté serveur.