テーマの永続化とフラッシュの防止

ページの読み込み時、ReactがlocalStorageを読み取って正しいテーマを適用するには、JavaScriptのダウンロード、解析、実行が必要です。この間、ブラウザーはデフォルトのスタイルで描画します。ユーザーがダークモードを好み、デフォルトがライトテーマの場合、テーマが修正される前に短時間、白い画面が表示されます。

この問題は、ほかのコードより先に同期的に実行されるインラインスクリプトをdocument headに配置することで解決できます。このスクリプトは直ちにlocalStorageを読み取り、document.documentElementにdata-themeを設定します。ブロッキングスクリプトなので、ブラウザーはコンテンツを描画する前にこの属性を適用できます。

非同期スクリプトや遅延スクリプトは、HTMLの解析後、場合によっては初回描画後に実行されます。それでは目的を果たせません。ブロッキングインラインスクリプトにはasync属性やdefer属性を付けず、外部ファイルから読み込まないでください。パフォーマンスへの影響を抑えるため、スクリプトはごく小さくする必要があります。

ブロッキングスクリプトは最小限にします。localStorage.getItem('theme')を読み取り、フォールバックとしてwindow.matchMedia('(prefers-color-scheme: dark)').matchesを確認し、その後document.documentElement.setAttribute('data-theme', theme)を呼び出します。プライベートブラウジングなどでlocalStorageが利用できない場合に備え、try-catchで囲んでください。

Next.jsでは、next/scriptのScriptコンポーネントをstrategy="beforeInteractive"とともに_document.js内で使用します。beforeInteractive戦略により、ページのJavaScriptが実行される前にスクリプトがページHTMLへ挿入され、Next.jsのビルドパイプラインでも同じブロッキング動作を実現できます。

ViteまたはCreate React Appのプロジェクトでは、index.htmlを直接編集し、ほかのスクリプトより前にインラインスクリプトタグをhead内へ配置します。index.htmlがブラウザーのエントリーポイントなので、Reactが起動する前にスクリプトが実行されます。100バイト未満に収まるよう、簡潔に記述してください。

サーバーレンダリングされたアプリでは、サーバーがリクエストとともに送信されたCookieからテーマを読み取れます。その後、サーバーはブラウザーへ送信する前に、レンダリング済みHTMLへdata-themeを設定します。最初のHTMLの1バイト目から正しいテーマが含まれるため、クライアント側での一瞬の表示崩れを完全に防げます。

一連の流れは次のとおりです。ブラウザーがHTMLをダウンロードし、パーサーがブロッキングインラインスクリプトに遭遇し、スクリプトがlocalStorageを読み取ってdata-themeを設定し、パーサーが処理を続け、正しいテーマでページが描画され、ReactがハイドレーションしてlocalStorageから同じテーマを取得します。ユーザーは最初から一貫したテーマを目にできます。

修正が機能することを確認するには、Chrome DevToolsを開いてNetworkタブへ移動し、通信速度をSlow 3Gに制限します。ページを再読み込みしてください。読み込み中にテーマが変わる場合は、表示崩れが解消されていません。ブロッキングスクリプトを配置すると、低速な接続でも初回描画から正しいテーマが表示されます。

Reactの初期状態がライトテーマで、ハイドレーション前にブロッキングスクリプトがダークテーマを設定した場合、Reactがハイドレーションの不一致を警告することがあります。これを避けるには、初回レンダリング時にもlocalStorageを読み取ってReactのテーマ状態を初期化し、ReactがレンダリングしたHTMLとブロッキングスクリプトが設定したDOMの状態を一致させます。

Storybookとテスト環境ではindex.htmlが読み込まれないため、ブロッキングスクリプトは実行されません。これらの環境でデフォルトのdata-theme属性を適用するデコレーターまたはテストセットアップを用意してください。これにより、コンポーネントを分離して開発する際の紛らわしい見た目の不一致を防げます。

誤ったテーマが一瞬表示されるのを防ぐには、document headでどのような種類のスクリプトを使用する必要がありますか？

描画が行われる前にlocalStorageを読み取り、data-themeを設定する小さなブロッキングインラインスクリプトをドキュメントヘッドへ挿入して、誤ったテーマが一瞬表示されるのを防ぎます。Next.jsではstrategy="beforeInteractive"を使用し、Vite/CRAではindex.htmlへ直接追加します。SSRアプリではCookieを読み取ってサーバー側でテーマを設定できます。