Persistindo o tema e evitando o flash

Quando uma página é carregada, o React precisa baixar, analisar e executar o JavaScript antes de poder ler localStorage e aplicar o tema correto. Durante esse intervalo, o navegador renderiza usando os estilos padrão. Se o usuário preferir o modo escuro, mas o padrão for claro, ele verá uma breve tela branca antes que o tema seja corrigido.

A correção consiste em um script embutido colocado no document head que seja executado de forma síncrona antes de qualquer outro código. Esse script lê localStorage imediatamente e define data-theme em document.documentElement. Como é um script bloqueante, o navegador aplica o atributo antes de renderizar qualquer conteúdo.

Scripts assíncronos ou adiados são executados depois que o HTML é analisado e, possivelmente, depois da primeira renderização. Isso anula todo o objetivo. O script embutido bloqueante não pode ter os atributos async ou defer e não deve ser carregado de um arquivo externo. O script deve ser pequeno para minimizar o custo de desempenho.

O script bloqueante é mínimo: leia localStorage.getItem('theme'), verifique window.matchMedia('(prefers-color-scheme: dark)').matches como alternativa e, em seguida, chame document.documentElement.setAttribute('data-theme', theme). Envolva-o em um tratamento de erros caso localStorage não esteja disponível na navegação privada.

No Next.js, use o componente Script de next/script com strategy="beforeInteractive" dentro de _document.js. A estratégia beforeInteractive insere o script no HTML da página antes da execução de qualquer JavaScript da página, obtendo o mesmo comportamento bloqueante no processo de compilação do Next.js.

Em um projeto Vite ou Create React App, edite index.html diretamente e coloque o elemento de script embutido no head, antes de qualquer outro script. Como index.html é o ponto de entrada do navegador, o script é executado antes da inicialização do React. Mantenha-o conciso para ficar abaixo de 100 bytes.

Em um aplicativo renderizado no servidor, o servidor pode ler o tema de um cookie enviado com a solicitação. Em seguida, o servidor define data-theme no HTML renderizado antes de enviá-lo ao navegador. Isso elimina completamente qualquer exibição momentânea no cliente, pois o tema correto está no primeiro byte do HTML.

O fluxo completo é: o navegador baixa o HTML, o analisador encontra o script embutido bloqueante, o script lê localStorage e define data-theme, o analisador continua, a página é renderizada com o tema correto, o React faz a hidratação e obtém o mesmo tema de localStorage. O usuário vê um único tema consistente desde o início.

Para verificar se a correção funciona, abra o Chrome DevTools, acesse a guia Rede e limite a velocidade para 3G lento. Recarregue a página. Se você perceber uma mudança de tema durante o carregamento, a exibição momentânea não foi corrigida. Com o script bloqueante configurado, a primeira renderização já deve mostrar o tema correto mesmo em conexões lentas.

Se o estado inicial do React tiver como padrão o tema claro, mas o script bloqueante tiver definido o tema escuro antes da hidratação, o React poderá emitir um aviso sobre uma incompatibilidade de hidratação. Evite isso inicializando o estado do tema do React também a partir da leitura de localStorage durante a renderização inicial, garantindo que o HTML renderizado pelo React corresponda ao estado do DOM definido pelo script bloqueante.

O Storybook e os ambientes de teste não carregam seu index.html, portanto o script bloqueante nunca é executado. Forneça um decorador ou uma configuração de teste que aplique um atributo data-theme padrão nesses ambientes. Isso evita inconsistências visuais confusas ao desenvolver componentes isoladamente.

Evite a exibição momentânea do tema incorreto inserindo um pequeno script embutido bloqueante no cabeçalho do documento que leia localStorage e defina data-theme antes de qualquer renderização. No Next.js, use strategy="beforeInteractive"; no Vite/CRA, adicione-o diretamente a index.html. Aplicativos com SSR podem ler um cookie para definir o tema no servidor.