Server Component Streaming support

[moroine]

I'd like to discuss about NextJs Server Component Streaming support following the comment #305 (comment)

I spent quite some time to dig-in both react-dsfr & dsfr codebases.

I understand the limitation regarding server sub-components, and I don't want to disable user interactions before everything is loaded.

From what I understand of dsfr, once activated, DSFR observes DOM modifications to integrate itself: https://github.com/GouvernementFR/dsfr/blob/5c3d27f9b0d5c060b411fcdfff663609f7eeb6fc/src/dsfr/core/script/api/modules/stage/stage.js#L62-L96

• Sub-components, even those server-side that would be streamed later, are correctly detected and working.
• The source of the problem is that DOM mutation is performed directly, even before hydration is complete. If I add a setTimeout of 300ms, then there are no more issues. But this is a rather unacceptable solution. Ideally, it should be possible to determine when hydration is complete to act as a useEffect would.
• The only hydration error I'm experiencing is the addition of data-fr-js-xx attributes: https://github.com/GouvernementFR/dsfr/blob/5c3d27f9b0283f02d674908e4ed93742833f49bf17a7/src/dsfr/core/script/api/modules/register/instance.js#L47 If I remove this line, everything works fine. I can't understand the purpose of this attribute (it doesn't seem to be read in the dsfr code). Ideally, if DSFR needs to keep such a reference, they could use a WeakMap 🤔

Regarding the hydration problem related to useIsDark, it's because the initialization value of isDark is inconsistent with the server once DSFR is initialized:

react-dsfr/src/useIsDark/client.ts

Lines 57 to 59 in 7789b02

	const isDark = $isAfterFirstEffect.current
	? $clientSideIsDark.current
	: ssrWasPerformedWithIsDark;

I think this can be resolved with the following code.

export const useIsDarkClientSide = () => {
  const [isDark, setIsDarkValue] = useState(ssrWasPerformedWithIsDark)
  useEffect(() => {
    if ($isAfterFirstEffect.current) {
      setIsDarkValue($clientSideIsDark.current);
    }
  }, [$clientSideIsDark.current, $isAfterFirstEffect.current]);
  const [, reRender] = useReducer(() => [], []);
  useEffect(() => {
    reRender();
  }, []);
  useRerenderOnChange($clientSideIsDark);
  useRerenderOnChange($isAfterFirstEffect);
  const setIsDark = useConstCallback(newIsDarkOrDeduceNewIsDarkFromCurrentIsDark => {
    const data_fr_js_value = document.documentElement.getAttribute(“data-fr-js”);
    const newColorScheme = (() => {
      switch (typeof newIsDarkOrDeduceNewIsDarkFromCurrentIsDark === “function”
        ? newIsDarkOrDeduceNewIsDarkFromCurrentIsDark(isDark)
        : newIsDarkOrDeduceNewIsDarkFromCurrentIsDark) {
        case “system”:
          return “system”;
        case true:
          return “dark”;
        case false:
          return “light”;
      }
    })();
    document.documentElement.setAttribute(data_fr_scheme, newColorScheme);
    if (data_fr_js_value !== “true”) {
      //NOTE: DSFR not started yet.
      document.documentElement.setAttribute(data_fr_theme, newColorScheme === “system” ? getSystemColorScheme() : newColorScheme);
      localStorage.setItem(“scheme”, newColorScheme);
    }
  });
  return {
    isDark,
    setIsDark
  };
};

But the problem, I think, will be a darkMode flickering on loading. A solution could be to save the darkMode in a cookie, which could be read by the server component to correctly initialize dark mode.

Otherwise, we could simply add a suppressHydratationWarning to the DSFR components: https://legacy.reactjs.org/docs/dom-elements.html#suppresshydrationwarning?"

[garronej]

I wrote a detailed response but forgot to send it for some reason.

Now I'm out, I'll send it later. But just to tell you I've pushed a patch with the fix you suggested about the isDark client state.
(Well different implementation but same idea)

[moroine]

Have a nice weekend

[garronej]

Hello @moroine,

The source of the problem is that DOM mutation is performed directly, even before hydration is complete. If I add a setTimeout of 300ms, then there are no more issues. But this is a rather unacceptable solution. Ideally, it should be possible to determine when hydration is complete to act as a useEffect would.

I'm not sure what level you're speaking from here.

In react-dsfr, the DSFR JS code is only started after <StartDsfrOnHydration /> is hydrated. You control where in the route tree this component is mounted. This acts as a declarative signal to react-dsfr that it's safe to start DSFR’s JS (and therefore begin DOM manipulations).

Once this component is hydrated, DSFR JS starts and begins observing the DOM, potentially annotating newly added elements synchronously. That’s what can cause hydration errors—especially with streamed HTML chunks.

When you mention the 300ms timeout, I assume you're referring to a delay inside @gouvfr/dsfr—between the moment a DOM element is added and the moment it's processed. If you're instead suggesting a timeout in @codegouvfr/react-dsfr or your application code, then I believe you're missing the point.

In any case, we both agree: relying on timeouts is not an acceptable solution.

---

Regarding the hydration problem related to useIsDark, it's because the initialization value of isDark is inconsistent with the server once DSFR is initialized:

Good catch! I'll revisit the implementation. You're right: on the first render, we should continue using ssrWasPerformedWithIsDark, even after the first useEffect has run—especially in the case of streamed components.

But the problem, I think, will be a darkMode flickering on loading.

That flickering only affects components using CSS-in-JS (like MUI). Native DSFR components, which rely on CSS variables, don’t flicker because the root HTML attribute is set early via suppressHydrationWarning in getHtmlAttributes.

A solution could be to save the darkMode in a cookie, which could be read by the server component to correctly initialize dark mode.

That's not a solution—it’s the only viable solution. It's a well-known limitation of CSS-in-JS: the only way to avoid flickering when implementing dark mode is to SSR different versions of the page depending on the user's preference.

For the Page Router, I provided doPersistDarkModePreferenceWithCookie:
https://react-dsfr.codegouv.studio/mui#next.js-improving-first-print

However, I didn’t port it to the App Router, because it’s not reasonable. It causes the server to regenerate pages for every request and, even then, it only works on subsequent loads—not the initial one.

Otherwise, we could simply add a suppressHydrationWarning to the DSFR components: https://legacy.reactjs.org/docs/dom-elements.html#suppresshydrationwarning?

This is already implemented.

---

The only practical way forward here is to use patch-package and apply the necessary adjustments to support React Server Components and streaming properly.

The idea would be to provide an attribute or a signal that tells DSFR when it's safe to mutate a DOM element.

I’ll explore how feasible this is in practice.

[moroine]

Hello @garronej,

That flickering only affects components using CSS-in-JS (like MUI). Native DSFR components, which rely on CSS variables, don’t flicker because the root HTML attribute is set early via suppressHydrationWarning in getHtmlAttributes.

When I mean adding suppressHydrationWarning, I was speaking about each component which adds the data-fr-js-xx attribute as suppressHydrationWarning is only 1 level deep.

However, I didn’t port it to the App Router, because it’s not reasonable. It causes the server to regenerate pages for every request and, even then, it only works on subsequent loads—not the initial one.

I agree.

---

The only practical way forward here is to use patch-package and apply the necessary adjustments to support React Server Components and streaming properly.
The idea would be to provide an attribute or a signal that tells DSFR when it's safe to mutate a DOM element.
I’ll explore how feasible this is in practice.

Isn't it possible to consider a PR on the @gouvfr/dsfr repository to add a mode configuration ? If we check the official documentation, they already have a mode react which is not implemented. And looks like they want to support it someday https://www.systeme-de-design.gouv.fr/prise-en-main-et-perimetre/developpeurs/api-javascript as they say:

à venir : implémentation spécifique pour lancement du moteur une fois React initialisé;

Maybe we can propose such an improvement ?

I was thinking about the issue over the weekend, and I was wondering if we could have in components from react-dsfr a useEffect which would add the the classname on first render ? I don't think it would be ideal, because I suspect a lot of css to not be applied directly, and this might cause trouble 🤔.

But if we could submit a PR to @gouvfr/dsfr which could be either:

• a condition within the stage.js to parse when an extra attribute is present like data-fr-ready
• or we could go for making all selectors conditional like for CheckboxSelector to require extra class fr-component-ready for exemple
• or we could change the Registration to add this conditionnal class

Note

Looks like theses solutions requires to update the stage.js file stage.js because the parse is only trigger on childList update, so mutating the classnames after initial render would prevent the @gouvfr/dsfr to register those elements.

[moroine]

@garronej any suggestion about the best way to handle this ?

[garronej]

@moroine I'm going to focus on react-dsfr for a bit to implement a key feature:
a one-config way to "un-dsfrify" an app.

The goal is to make it easy for public service apps to be white-labeled and deployed in other contexts.

I'll likely be patching @gouvfr/dsfr with patch-package during this work — I can also take a look at server component streaming in parallel.