Values derived from useColorMode() can be stale when rendering in prod mode

[fvsch]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

• I'm using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io.
• I have read the console error message carefully (if applicable).

Description

The value returned by the useColorMode hook from @docusaurus/theme-common seems to have a strange behavior when:

1. Building for production and/or using React in prod mode (npm run build && npm run serve).
2. window.localStorage.theme is 'dark' while the themeConfig.colorMode.defaultMode value is 'light', or window.localStorage.theme is 'light' while the themeConfig.colorMode.defaultMode value is 'dark'.

Then trying to use the colorMode value set the value of DOM attributes ends up generating a DOM with incorrect attribute values:

import { useColorMode } from "@docusaurus/theme-common";
import React from "react";

export default function ColorModeTest() {
  const { colorMode } = useColorMode();
  return (
    <div title={colorMode}>{colorMode}</div>
  );
}

In the conditions described above, if the themeConfig.colorMode.defaultMode value is 'light' and the localStorage.theme value is 'dark':

1. The generated HTML will be: <div title="light">light</div>
2. The hydrated DOM will be: <div title="light">dark</div>

This is particularly troublesome when you have UI components that support both dark and light themes and rely on HTML attributes to set the correct color theme on the component itself (e.g. in order to display a light component in a dark context for visual emphasis).

Reproducible demo

https://github.com/fvsch/docusaurus-use-color-mode-stale-value

Steps to reproduce

1. Check out https://github.com/fvsch/docusaurus-use-color-mode-stale-value
2. Install dependencies, build for prod and serve that build: npm install && npm run build && npm run serve
3. The home page of the demo should be using a light theme.
4. Click the theme switching button on the top right to switch to the dark theme.
5. Reload the page.

Expected behavior

The values derived from the colorMode, whether they're text nodes or attribute nodes, should be in sync and reflect the localStorage.theme value.

In the last step, the visual result should be:

Actual behavior

Attribute values that are derived from the colorMode value seem to be outdated.

In the last step, the visual result is:

Your environment

• Public source code: https://github.com/fvsch/docusaurus-use-color-mode-stale-value/blob/main/src/components/ColorModeTest/index.js
• Public site URL: n.a. (but currently affects https://developer.stackblitz.com/ too)
• Docusaurus version used: 2.0.1
• React version used: 17.0.2
• Environment name and version (e.g. Chrome 89, Node.js 16.4): all browsers tested (Firefox, Chrome and Safari); Node 16.17.0.
• Operating system and version (e.g. Ubuntu 20.04.2 LTS): macOS 12.5, probably happens on Linux too (happens when building our site on CI); haven't tried on Windows but I don't expect a difference here.

Self-service

• I'd be willing to fix this bug myself.

[slorber]

Quick StackBlitz repro link: https://stackblitz.com/github/fvsch/docusaurus-use-color-mode-stale-value?file=src%2Fcomponents%2FColorModeTest%2Findex.js

---

Agree there is likely a React hydration problem.

const getInitialColorMode = (defaultMode: ColorMode | undefined): ColorMode =>
  ExecutionEnvironment.canUseDOM
    ? coerceToColorMode(document.documentElement.getAttribute('data-theme'))
    : coerceToColorMode(defaultMode);

  const [colorMode, setColorModeState] = useState(
    getInitialColorMode(defaultMode),
  );

Again related blog post: https://www.joshwcomeau.com/react/the-perils-of-rehydration/

Afaik it has been claimed in a clearer way more recently by the React core team that the SSR/CSR must 100% match. React 18 introduces a onRecoverableError callback which usually notice you of hydration mismatches, and in this React 18 POC PR (#7855) I noticed we had some.

In this case I think we can't technically init our React state with the correct value, but instead should always init it to the default color mode, and then trigger a new re-render to fix it after hydration.

const [colorMode, setColorModeState] = useState(defaultMode);

useLayoutEffect(() => {
  coerceToColorMode(document.documentElement.getAttribute('data-theme'))
},[])

This should fix the SSR/CSR mismatch, but this is a bit annoying unfortunately, as it will mean some components will render first with the wrong colorMode and then eventually re-render with the right one

[dionysuzx]

any status update or timeline on this? seems to be an important one. I have an logo with a font color that I need to change dynamically on the current color theme, and currently this bug means I need to keep the theme switcher toggle disabled for now. Thanks!

[slorber]

I'll probably fix this as part of the React 18 upgrade, as we'll be able to see hydration error messages that I would have to fix one by one to complete this migration.

Note you might not need useColorMode, you can also use html[data-theme="dark" CSS selectors and we also have a ThemedImage component: https://docusaurus.io/docs/markdown-features/assets#themed-images