Persistenza del tema e prevenzione del flash

Quando una pagina viene caricata, React deve scaricare, analizzare ed eseguire JavaScript prima di poter leggere localStorage e applicare il tema corretto. Durante questo intervallo, il browser esegue il rendering utilizzando gli stili predefiniti. Se l'utente preferisce la modalità scura ma il valore predefinito è light, vedrà un breve flash bianco prima che il tema venga corretto.

La soluzione consiste in uno script inline inserito nel document head, che viene eseguito in modo sincrono prima di qualsiasi altro codice. Lo script legge immediatamente localStorage e imposta data-theme su document.documentElement. Poiché è uno script bloccante, il browser applica l'attributo prima di eseguire il rendering di qualsiasi contenuto.

Gli script asincroni o differiti vengono eseguiti dopo l'analisi dell'HTML e potenzialmente anche dopo il primo rendering. Questo vanifica completamente lo scopo della soluzione. Lo script inline bloccante non deve avere gli attributi async o defer e non deve essere caricato da un file esterno. Deve essere molto piccolo per ridurre al minimo il costo sulle prestazioni.

Lo script bloccante deve essere minimale: leggete localStorage.getItem('theme'), controllate window.matchMedia('(prefers-color-scheme: dark)').matches come alternativa e poi chiamate document.documentElement.setAttribute('data-theme', theme). Racchiudetelo in un blocco try-catch nel caso in cui localStorage non sia disponibile durante la navigazione privata.

In Next.js, utilizzate il componente Script di next/script con strategy="beforeInteractive" all'interno di _document.js. La strategia beforeInteractive inserisce lo script nell'HTML della pagina prima dell'esecuzione di qualsiasi JavaScript della pagina, ottenendo lo stesso comportamento bloccante nella pipeline di build di Next.js.

In un progetto Vite o Create React App, modificate direttamente index.html e inserite il tag dello script inline nel head, prima di qualsiasi altro script. Poiché index.html è il punto di ingresso del browser, lo script viene eseguito prima dell'avvio di React. Mantenetelo conciso, in modo che resti sotto i 100 byte.

In un'applicazione con rendering lato server, il server può leggere il tema da un cookie inviato con la richiesta. Può quindi impostare data-theme nell'HTML generato prima di inviarlo al browser. In questo modo si evita completamente il flash lato client, perché il tema corretto è presente già nel primo byte dell'HTML.

Il flusso completo è il seguente: il browser scarica l'HTML, l'analizzatore incontra lo script inline bloccante, lo script legge localStorage e imposta data-theme, l'analisi prosegue, la pagina viene visualizzata con il tema corretto, quindi React completa l'hydration e recupera lo stesso tema da localStorage. L'utente vede un tema coerente fin dall'inizio.

Per verificare che la soluzione funzioni, aprite Chrome DevTools, accedete alla scheda Network e impostate il throttling su Slow 3G. Ricaricate la pagina. Se durante il caricamento vedete cambiare il tema, il flash non è stato eliminato. Con lo script bloccante attivo, il primo rendering dovrebbe già mostrare il tema corretto anche con connessioni lente.

Se lo stato iniziale di React è impostato su light ma lo script bloccante ha impostato dark prima dell'hydration, React potrebbe mostrare un avviso di discrepanza durante l'hydration. Evitate il problema inizializzando lo stato del tema di React leggendo anch'esso localStorage durante il rendering iniziale, così l'HTML generato da React corrisponde allo stato del DOM impostato dallo script bloccante.

Storybook e gli ambienti di test non caricano il vostro index.html, quindi lo script bloccante non viene mai eseguito. Fornite un decorator o una configurazione di test che applichi un attributo data-theme predefinito in questi ambienti. In questo modo eviterete incoerenze visive durante lo sviluppo isolato dei componenti.

Quale tipo di script deve essere utilizzato nel head del documento per prevenire il flash del tema errato?

Prevenite il flash del tema errato inserendo nel head del documento un piccolo script inline bloccante che legga localStorage e imposti data-theme prima di qualsiasi rendering. In Next.js utilizzate strategy="beforeInteractive", mentre in Vite/CRA aggiungetelo direttamente a index.html. Le applicazioni SSR possono leggere un cookie per impostare il tema lato server.