refactor: fix the SSR/CSR mismatch

[HsiangNianian]

What happened?

Due to the CSS not being written in a format supported by Webpack¹, I imported postcss-preset-env(a10ec67) and created the customPostCssPlugin function(091a16f) (the code is provided below) to enable runtime plugins, achieving the goal of using preset environment CSS. This has clearly been effective.

function customPostCssPlugin() {
  return {
    name: "custom-postcss",
    configurePostCss(options) {
      // Append new PostCSS plugins here
      options.plugins.push(require("postcss-preset-env")); // allow newest CSS syntax
      return options;
    }
  };
}

---

The Changes

Important

There is one remaining warning, similar to the previous ones.
This final error is still due to the CSS format, but it cannot be detected by the customPostCssPlugin.

	before
	after

So you can continue to make modifications from this perspective to try to get the compilation build workflow to pass. Since it's already quite late (USTC +8), I currently don't have the ability to further investigate any suspicious CSS syntax.

This is the everything about WA.

---

Literally, I noticed the error about useColorMode() in prod mode. Values derived from useColorMode() can be stale when rendering in prod mode, so we have to avoid to use import { useColorMode } from '@docusaurus/theme-common'; and this 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),
  );

Asfaik, react 18 introduces a onRecoverableError callback which usually notice you of hydration mismatches.

In this case we can't technically init 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.

Footnotes

1. https://github.com/webpack/webpack/issues/14893 ↩

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
farm-fe-github-io	❌ Failed (Inspect)			Sep 12, 2024 5:47am

[wre232114]

Thanks!

[HsiangNianian]

Alternatively, you could use themed-images, which might be the best solution aside from the aforementioned approaches and using:

// You might be fine with the following, but use at your own risks, 
// and be aware it is likely to create issues down the line
const isDarkMode = document.documentElement.getAttribute('data-theme') === "dark";

Docusaurus doesn't have good support for "legacy CSS-in-JS libs" (StyledComponents, Emotion, JSS, MUI...), that require collecting styles during the rendering process (see also facebook/docusaurus#3236).

Warning

However, you may have noticed that ThemedImage seems to only support file-based resources, rather than components like <StarrySky /> or <AuroraBackground />. After modifying it(see also 3ec0863), I was able to get it to build, but the background does not display correctly.

---

The Lives

	light
	dark

[HsiangNianian]

Even though the compilation build workflow is successful, the actual effect is still problematic(see also #146 (comment))

[fu050409]

Thanks for your work :)

@ErKeLost take a look?

[ErKeLost]

@HsiangNianian thank you for your work，I will try to repair the next work