Restore build configuration schema

Author: fhammerschmidt

apps/docs/markdown-pages/docs/manual/build-configuration-schema.mdx

@@ -7,6 +7,4 @@ section: "Build System"
 order: 3
 ---
 
-<Suspense>
-  <Docson tag="master" />
-</Suspense>
+<Docson tag="master" />

apps/docs/src/components/DocsonLazy.res

@@ -1 +1,25 @@
-let make = React.lazy_(() => import(Docson.make))
+module Internal = {
+  let make = React.lazy_(() => import(Docson.make))
+}
+
+let fallback = <div id="docson-root" />
+
+@react.component
+let make = (~tag) => {
+  let (isMounted, setMounted) = React.useState(_ => false)
+
+  React.useEffect(() => {
+    setMounted(_ => true)
+    None
+  }, [])
+
+  // Docson mutates the DOM and depends on browser globals, so keep the first
+  // client render identical to the prerendered HTML and load it after hydration.
+  if isMounted {
+    <React.Suspense fallback>
+      <Internal tag />
+    </React.Suspense>
+  } else {
+    fallback
+  }
+}

apps/docs/vite.config.mjs

@@ -10,6 +10,11 @@ const excludedFiles = ["lib/**", "**/*.res", "**/*.resi"];
 
 export default defineConfig({
   envDir: "../..",
+  // Some older browser-targeted dependencies, notably docson, still reference
+  // Node's `global` identifier. Rewrite it to the standards-based browser global.
+  define: {
+    global: "globalThis",
+  },
   plugins: [
     tailwindcss(),
     reactRouter(),