Сохранение темы и предотвращение мерцания

При загрузке страницы React должен загрузить, разобрать и выполнить JavaScript, прежде чем сможет прочитать localStorage и применить правильную тему. В этот промежуток браузер отображает страницу с использованием стилей по умолчанию. Если пользователь предпочитает тёмную тему, а значение по умолчанию — светлое, он на короткое время видит белую вспышку, прежде чем тема исправится.

Решение заключается во встроенном скрипте, размещённом в document head, который синхронно выполняется до любого другого кода. Этот скрипт сразу читает localStorage и устанавливает data-theme в document.documentElement. Поскольку скрипт блокирует выполнение, браузер устанавливает атрибут до отрисовки содержимого.

Асинхронные скрипты и скрипты с отложенным выполнением запускаются после разбора HTML и, возможно, после первой отрисовки. Это лишает решение смысла. Встроенный блокирующий скрипт не должен иметь атрибутов async или defer и не должен загружаться из внешнего файла. Скрипт должен быть очень небольшим, чтобы свести затраты производительности к минимуму.

Блокирующий скрипт должен быть минимальным: прочитайте localStorage.getItem('theme'), проверьте window.matchMedia('(prefers-color-scheme: dark)').matches как запасной вариант, а затем вызовите document.documentElement.setAttribute('data-theme', theme). Оберните его в обработчик исключений на случай, если localStorage недоступен в режиме приватного просмотра.

В Next.js используйте компонент Script из next/script со strategy="beforeInteractive" внутри _document.js. Стратегия beforeInteractive вставляет скрипт в HTML страницы до запуска любого JavaScript страницы, обеспечивая такое же блокирующее поведение в конвейере сборки Next.js.

В проекте на Vite или Create React App отредактируйте index.html напрямую и разместите встроенный тег скрипта в head перед всеми остальными скриптами. Поскольку index.html является точкой входа для браузера, скрипт выполняется до запуска React. Сделайте его кратким, чтобы уложиться в 100 байт.

В приложении с серверной отрисовкой сервер может прочитать тему из cookie, отправленной вместе с запросом. Затем сервер устанавливает data-theme в сгенерированном HTML до отправки его браузеру. Это полностью устраняет вспышку на стороне клиента, поскольку правильная тема присутствует уже в самом первом байте HTML.

Полный процесс выглядит так: браузер загружает HTML, анализатор встречает встроенный блокирующий скрипт, скрипт читает localStorage и устанавливает data-theme, анализатор продолжает работу, страница отображается с правильной темой, React выполняет гидратацию и получает ту же тему из localStorage. Пользователь с самого начала видит одну и ту же тему.

Чтобы проверить исправление, откройте Chrome DevTools, перейдите на вкладку «Сеть» и установите ограничение скорости «Медленный 3G». Перезагрузите страницу. Если во время загрузки тема меняется, вспышка не устранена. При наличии блокирующего скрипта первая отрисовка уже должна показывать правильную тему даже при медленном соединении.

Если начальное состояние React по умолчанию устанавливается в светлую тему, а блокирующий скрипт до гидратации установил тёмную, React может предупредить о несоответствии при гидратации. Чтобы избежать этого, при начальном отображении также инициализируйте состояние темы React чтением из localStorage. Тогда HTML, отображённый React, будет соответствовать состоянию DOM, установленному блокирующим скриптом.

Storybook и тестовые окружения не загружают ваш index.html, поэтому блокирующий скрипт не выполняется. Добавьте декоратор или настройку тестов, которая устанавливает атрибут data-theme по умолчанию в этих окружениях. Это предотвращает confusing визуальные несоответствия при изолированной разработке компонентов.

Предотвратите краткое отображение неправильной темы, добавив небольшой встроенный блокирующий скрипт в заголовок документа. Он должен прочитать localStorage и установить data-theme до первой отрисовки. В Next.js используйте strategy="beforeInteractive", а в Vite и Create React App добавьте скрипт непосредственно в index.html. Приложения SSR могут прочитать cookie и установить тему на стороне сервера.