Theme speichern und Aufblitzen verhindern

Beim Laden einer Seite muss React JavaScript herunterladen, parsen und ausführen, bevor localStorage gelesen und das korrekte Theme angewendet werden kann. Während dieser Verzögerung rendert der Browser mit den Standardstilen. Wenn der Benutzer den dunklen Modus bevorzugt, Ihr Standardwert aber „light“ ist, sieht er kurz ein weißes Aufblitzen, bevor das Theme korrigiert wird.

Die Lösung ist ein Inline-Script im document head, das synchron vor jedem anderen Code ausgeführt wird. Dieses Script liest sofort localStorage und setzt data-theme auf document.documentElement. Da es sich um ein blockierendes Script handelt, wendet der Browser das Attribut an, bevor irgendein Inhalt gezeichnet wird.

Asynchrone oder verzögerte Scripts werden ausgeführt, nachdem das HTML geparst wurde und möglicherweise sogar nach dem ersten Paint. Damit wäre der gesamte Zweck verfehlt. Das blockierende Inline-Script darf keine async- oder defer-Attribute besitzen und darf nicht aus einer externen Datei geladen werden. Das Script muss sehr klein sein, um die Performance-Kosten zu minimieren.

Das blockierende Script ist minimal: Lesen Sie localStorage.getItem('theme'), prüfen Sie als Fallback window.matchMedia('(prefers-color-scheme: dark)').matches und rufen Sie anschließend document.documentElement.setAttribute('data-theme', theme) auf. Schließen Sie den Code in einen Try-Catch-Block ein, falls localStorage beim privaten Surfen nicht verfügbar ist.

Verwenden Sie in Next.js die Script-Komponente aus next/script mit strategy="beforeInteractive" innerhalb von _document.js. Die Strategie beforeInteractive fügt das Script in das Seiten-HTML ein, bevor JavaScript der Seite ausgeführt wird, und erzielt dadurch dasselbe blockierende Verhalten in der Next.js-Build-Pipeline.

Bearbeiten Sie in einem Vite- oder Create-React-App-Projekt direkt die Datei index.html und platzieren Sie das Inline-Script-Tag im head vor allen anderen Scripts. Da index.html der Einstiegspunkt für den Browser ist, wird das Script ausgeführt, bevor React startet. Halten Sie es kurz, damit es weniger als 100 Byte umfasst.

In einer serverseitig gerenderten Anwendung kann der Server das Theme aus einem mit der Anfrage gesendeten Cookie lesen. Anschließend setzt der Server data-theme im gerenderten HTML, bevor er es an den Browser sendet. Dadurch wird jedes clientseitige Aufblitzen vermieden, weil das korrekte Theme bereits im allerersten Byte des HTMLs enthalten ist.

Der vollständige Ablauf ist: Der Browser lädt das HTML herunter, der Parser stößt auf das blockierende Inline-Script, das Script liest localStorage und setzt data-theme, der Parser fährt fort, die Seite wird mit dem korrekten Theme gezeichnet, und React führt die Hydration durch und übernimmt dasselbe Theme aus localStorage. Der Benutzer sieht von Anfang an durchgehend dasselbe Theme.

Öffnen Sie zum Überprüfen der Lösung die Chrome DevTools, wechseln Sie zum Tab „Network“ und drosseln Sie die Verbindung auf Slow 3G. Laden Sie die Seite neu. Wenn sich das Theme während des Ladens ändert, ist das Aufblitzen nicht behoben. Mit dem blockierenden Script sollte bereits der erste Paint auch bei langsamen Verbindungen das korrekte Theme anzeigen.

Wenn Ihr initialer React-State standardmäßig auf „light“ steht, das blockierende Script aber vor der Hydration „dark“ gesetzt hat, gibt React möglicherweise eine Warnung wegen eines Hydration-Mismatch aus. Vermeiden Sie dies, indem Sie den React-Theme-State bereits beim initialen Rendern ebenfalls aus localStorage lesen. So stimmt das von React gerenderte HTML mit dem vom blockierenden Script gesetzten DOM-Zustand überein.

Storybook- und Testumgebungen laden Ihre index.html nicht, daher wird das blockierende Script dort nie ausgeführt. Stellen Sie in diesen Umgebungen über einen Decorator oder ein Test-Setup ein standardmäßiges data-theme-Attribut bereit. Dadurch vermeiden Sie verwirrende visuelle Abweichungen bei der isolierten Entwicklung von Komponenten.

Welche Art von Script muss im Document-Head verwendet werden, um das Aufblitzen des falschen Themes zu verhindern?

Verhindern Sie das Aufblitzen des falschen Themes, indem Sie ein kleines blockierendes Inline-Script in den Document-Head einfügen, das localStorage liest und data-theme vor dem ersten Paint setzt. Verwenden Sie in Next.js strategy="beforeInteractive" und fügen Sie das Script in Vite/CRA direkt zu index.html hinzu. SSR-Anwendungen können ein Cookie lesen, um das Theme serverseitig zu setzen.