@decocms/start 0.28.1 → 0.28.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "0.28.1",
+  "version": "0.28.2",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",

package/src/hooks/DecoPageRenderer.tsx

@@ -42,15 +42,20 @@ function syncThenable(mod: {
 
 function getLazyComponent(key: string) {
   if (!lazyCache.has(key)) {
+    // If sync-registered, wrap in a pre-fulfilled lazy so React.lazy
+    // resolves synchronously — same tree structure as lazy-only path.
+    const sync = getSyncComponent(key);
+    if (sync) {
+      lazyCache.set(key, lazy(() => syncThenable({ default: sync })));
+      return lazyCache.get(key)!;
+    }
+
     const registry = getSectionRegistry();
     const loader = registry[key];
     if (!loader) return null;
     lazyCache.set(
       key,
       lazy(() => {
-        // If already resolved (from preloadSectionComponents on server,
-        // or from route loader on client SPA), return a sync thenable.
-        // React reads thenable.status/value synchronously — no Suspense.
         const resolved = getResolvedComponent(key);
         if (resolved) {
           return syncThenable({ default: resolved });
@@ -409,6 +414,25 @@ function mergeSections(resolved: ResolvedSection[], deferred: DeferredSection[])
 // DecoPageRenderer — renders top-level resolved sections from a CMS page
 // ---------------------------------------------------------------------------
 
+// ---------------------------------------------------------------------------
+// IdleHydrationBoundary — delays hydration of below-fold sections until idle
+// ---------------------------------------------------------------------------
+
+function IdleHydrationBoundary({ children }: { children: ReactNode }) {
+  const [ready, setReady] = useState(typeof document === "undefined"); // SSR: always ready
+  useEffect(() => {
+    if (typeof requestIdleCallback === "function") {
+      const id = requestIdleCallback(() => setReady(true));
+      return () => cancelIdleCallback(id);
+    }
+    // Fallback for browsers without requestIdleCallback
+    const id = setTimeout(() => setReady(true), 50);
+    return () => clearTimeout(id);
+  }, []);
+  // Before ready, return null — React preserves SSR HTML via Suspense fallback={null}
+  return ready ? <>{children}</> : null;
+}
+
 interface Props {
   sections: ResolvedSection[];
   deferredSections?: DeferredSection[];
@@ -470,32 +494,27 @@ export function DecoPageRenderer({
           .replace(/\.tsx$/, "")
           .replace(/^site-sections-/, "");
 
-        // Only use sync path for sections explicitly registered via registerSectionsSync.
-        // DO NOT fallback to getResolvedComponent: that is populated server-side by
-        // preloadSectionComponents but NOT on the client, causing hydration mismatches
-        // (server renders <ul>, client renders <Suspense> for the same component).
-        const SyncComp = getSyncComponent(section.component);
-        if (SyncComp) {
-          return (
-            <section key={`${section.key}-${index}`} id={sectionId} data-manifest-key={section.key}>
-              <SectionErrorBoundary sectionKey={section.key} fallback={errFallback}>
-                <SyncComp {...section.props} />
-              </SectionErrorBoundary>
-            </section>
-          );
-        }
-
-        // Fallback: React.lazy with syncThenable for pre-loaded modules.
-        // fallback={null} preserves server HTML during hydration.
+        // Unified render path: always use React.lazy + Suspense.
+        // For sync-registered components, getLazyComponent wraps them in a
+        // pre-fulfilled lazy (via syncThenable) so React renders them
+        // synchronously — same behavior as the old sync path, but with an
+        // identical tree structure on both server and client (always has
+        // <Suspense>). This prevents hydration mismatches when sites remove
+        // registerSectionsSync.
         const LazyComponent = getLazyComponent(section.component);
         if (!LazyComponent) return null;
 
+        const isAboveFold = item.originalIndex < 3;
+        const content = (
+          <Suspense fallback={null}>
+            <LazyComponent {...section.props} />
+          </Suspense>
+        );
+
         return (
           <section key={`${section.key}-${index}`} id={sectionId} data-manifest-key={section.key}>
             <SectionErrorBoundary sectionKey={section.key} fallback={errFallback}>
-              <Suspense fallback={null}>
-                <LazyComponent {...section.props} />
-              </Suspense>
+              {isAboveFold ? content : <IdleHydrationBoundary>{content}</IdleHydrationBoundary>}
             </SectionErrorBoundary>
           </section>
         );

package/src/routes/cmsRoute.ts

@@ -50,6 +50,19 @@ import { type Device, detectDevice } from "../sdk/useDevice";
 
 const isServer = typeof document === "undefined";
 
+// Section chunk manifest — maps section keys to chunk filenames.
+// Generated by decoVitePlugin's generateBundle hook. Used to emit
+// <link rel="modulepreload"> hints for eager sections.
+let sectionChunkMap: Record<string, string> = {};
+
+/**
+ * Set the section chunk manifest. Called by the site's worker entry
+ * or setup after loading the manifest.
+ */
+export function setSectionChunkMap(map: Record<string, string>): void {
+  sectionChunkMap = map;
+}
+
 // ---------------------------------------------------------------------------
 // Server function — loads a CMS page, runs section loaders, detects cache
 // ---------------------------------------------------------------------------
@@ -251,6 +264,7 @@ type CmsPageLoaderData = {
   cacheProfile?: CacheProfile;
   seo?: PageSeo;
   device?: Device;
+  resolvedSections?: Array<{ component: string }>;
 } | null;
 
 // ---------------------------------------------------------------------------
@@ -386,6 +400,16 @@ function buildHead(
     links.push({ rel: "canonical", href: canonical });
   }
 
+  // Modulepreload hints for eager section chunks
+  if (loaderData?.resolvedSections) {
+    for (const s of loaderData.resolvedSections) {
+      const chunkFile = sectionChunkMap[s.component];
+      if (chunkFile) {
+        links.push({ rel: "modulepreload", href: `/${chunkFile}` });
+      }
+    }
+  }
+
   // JSON-LD structured data — rendered as <script type="application/ld+json"> in <head>
   const scripts: Array<{ type: string; children: string }> = [];
   if (seo?.jsonLDs?.length) {

package/src/routes/index.ts

@@ -11,6 +11,7 @@ export {
   loadCmsHomePage,
   loadCmsPage,
   loadDeferredSection,
+  setSectionChunkMap,
 } from "./cmsRoute";
 export { CmsPage, NotFoundPage } from "./components";
 export type { PageSeo } from "../cms/resolve";

package/src/vite/plugin.js

@@ -88,6 +88,27 @@ export function decoVitePlugin() {
         env.optimizeDeps.esbuildOptions.jsxImportSource = "react";
       }
     },
+
+    generateBundle(_, bundle) {
+      // Build a mapping from section key to chunk filename.
+      // Sites use this to emit <link rel="modulepreload"> for eager sections.
+      const map = {};
+      for (const [fileName, chunk] of Object.entries(bundle)) {
+        if (chunk.type === "chunk" && chunk.facadeModuleId) {
+          const match = chunk.facadeModuleId.match(/\/(sections\/.+\.tsx)$/);
+          if (match) {
+            map["site/" + match[1]] = fileName;
+          }
+        }
+      }
+      if (Object.keys(map).length > 0) {
+        this.emitFile({
+          type: "asset",
+          fileName: "section-chunks.json",
+          source: JSON.stringify(map),
+        });
+      }
+    },
   };
 
   return plugin;