トラブルシューティング
よくある症状の原因と直し方です。エラー文で探すときは、ページの中を検索してください。
このページの内容
再読み込みで一瞬出るライト
原因
インラインスクリプトが、最初の描画の前に走っていません。多いのは、CSPがスクリプトを止めている場合と、スクリプトがスタイルシートの後ろにあってその読み込みを待つ場合です。
直し方
コンソールにCSPの違反が出ていれば、次の「CSPで止まるスクリプト」を見てください。出ていなければ、<ColorSchemeScript />をルートレイアウトの<head>に置きます。@k8ordo/frameworkを使っていないときは、送られるHTMLでスクリプトがどのスタイルシートよりも前にあるかを確かめます。
CSPで止まるスクリプト
原因
スクリプトを制限するポリシーが、インラインスクリプトを許可していません。ハッシュで許可している場合は、ColorSchemeScriptと違うdefaultPreferenceやthemeColorで計算したハッシュか、古いバージョンのハッシュを書き写していることがあります。
直し方
nonceで許可するなら、ColorSchemeScriptのnonceにリクエストごとのnonceを渡します(@k8ordo/frameworkのserverモードではnonce())。ハッシュで許可するなら、ColorSchemeScriptと同じdefaultPreferenceとthemeColorをcolorSchemeScriptHash()に渡し、ポリシーを組み立てるたびに計算します。'unsafe-inline'は使いません。ほかのインラインスクリプトまで許可してしまいます。詳しくはCSPを見てください。
A tree hydrated but some attributes of the server rendered HTML didn't match
原因
インラインスクリプトが付けたclass="dark"は、サーバーのHTMLにはありません。開発ビルドのReactは<html>の属性をpropsと比べ、このclassの食い違いを警告します。
直し方
<html>にsuppressHydrationWarningを付けます。止まるのは<html>自身の属性の警告だけです。ページの中の食い違いは、これまでどおり報告されます。ハイドレーションは属性を書き戻さないので、クラスは残ります。
配色に従わないフォーム部品
原因
ブラウザが自分で描く部品の配色は、CSSのcolor-schemeプロパティで決まります。このパッケージはこのプロパティを設定しません。@k8ordo/uiを使っていない場合は、自分で宣言します。color-scheme: light darkと書いている場合は、ブラウザがOSの設定で選ぶので、訪問者の選択とずれます。
直し方
:rootにcolor-scheme: lightを、.darkにcolor-scheme: darkを宣言します。詳しくはdarkクラスのスタイルを見てください。
クラスを読まないTailwind CSSのdark:
原因
Tailwind CSS 4のdark:は、既定ではprefers-color-schemeを読みます。OSの設定には従いますが、訪問者が選んだ配色には従いません。
直し方
スタイルシートで@custom-variant dark (&:where(.dark, .dark *));を宣言します。dark:がクラスを読むようになります。@k8ordo/uiのtailwind.cssを読み込んでいれば、すでに宣言されています。詳しくはdarkクラスのスタイルを見てください。
読み込み直後に反転するアイコン
原因
サーバーは保存した選択を読めないので、既定値で描きます。schemeで出し分けたマークアップは、ハイドレーションが終わるまで既定値の配色のままです。
直し方
両方を描いてdark:で片方を隠すか、use(browser())を<Suspense>の中で呼んでブラウザでだけ描きます。詳しくは切り替えボタンを見てください。
useColorScheme needs <ColorSchemeProvider> above it
原因
useColorScheme()を呼んだコンポーネントの上に、プロバイダがありません。よくあるのは、プロバイダが入れ子のレイアウトにある場合と、テストでwrapperを渡していない場合です。
直し方
プロバイダをルートレイアウトの<body>の中に置き、ページ全体を包みます。テストでは、プロバイダをrenderHookのwrapperに渡します。
OSの設定に従わない配色
原因
OSの設定に従うのは、訪問者が何も選んでいない間だけです。一度ライトかダークを選ぶと、その選択が優先されます。プロバイダのdefaultPreferenceが'system'でない場合も、OSの設定は使われません。
直し方
setPreference('system')を呼ぶと、保存した選択が消えて既定値に戻ります。訪問者が自分で戻せるように、切り替えには「システム」を含む3択を用意します。
localStorageの書き換えを無視する配色
原因
タブの間では、storageイベントで選択を伝えます。このイベントは、書き込んだタブ自身では発火しません。同じタブでlocalStorage.setItemを直接呼んでも、プロバイダは再読み込みまで新しい値を読みません。
直し方
選択はsetPreferenceで変えます。同じオリジンのページを開いているほかのタブにも伝わります。詳しくは設定の保存先を見てください。
Encountered a script tag while rendering React component
原因
テストのようにブラウザだけで描くと、ReactはColorSchemeScriptが描くインラインの<script>を実行しません。開発ビルドのReactは、そのことをコンソールにエラーとして出します。
直し方
テストではColorSchemeScriptを描かず、プロバイダだけをwrapperに渡します。テストで見る<html>のクラスは、プロバイダのeffectが付けています。詳しくはテストを見てください。