@decocms/start 0.25.5 → 0.26.0

package/package.json

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

package/src/admin/index.ts

@@ -9,7 +9,7 @@ export {
 } from "./invoke";
 export { LIVE_CONTROLS_SCRIPT } from "./liveControls";
 export { handleMeta, setMetaData } from "./meta";
-export { handleRender, setRenderShell } from "./render";
+export { handleRender, setPreviewWrapper, setRenderShell } from "./render";
 export {
   composeMeta,
   getRegisteredLoaders,

package/src/admin/render.ts

@@ -4,8 +4,9 @@ import { getSection } from "../cms/registry";
 import { resolveValue, WELL_KNOWN_TYPES } from "../cms/resolve";
 import { buildHtmlShell } from "../sdk/htmlShell";
 import { LIVE_CONTROLS_SCRIPT } from "./liveControls";
+import { getPreviewWrapper } from "./setup";
 
-export { setRenderShell } from "./setup";
+export { setRenderShell, setPreviewWrapper } from "./setup";
 
 function wrapInHtmlShell(sectionHtml: string): string {
   return buildHtmlShell({ body: sectionHtml, script: LIVE_CONTROLS_SCRIPT });
@@ -28,7 +29,10 @@ async function renderOneSection(section: Record<string, unknown>): Promise<strin
     const { __resolveType: _, ...sectionProps } = section;
     const { renderToString } = await import("react-dom/server");
     const mod = await sectionLoader();
-    return renderToString(createElement(mod.default, sectionProps));
+    const element = createElement(mod.default, sectionProps);
+    const Wrapper = getPreviewWrapper();
+    const wrapped = Wrapper ? createElement(Wrapper, null, element) : element;
+    return renderToString(wrapped);
   } catch (error) {
     return `<div style="padding:8px;color:red;font-size:12px;">Error rendering ${resolveType}: ${(error as Error).message}</div>`;
   }
@@ -161,7 +165,10 @@ export async function handleRender(request: Request): Promise<Response> {
       const { __resolveType: _, ...cleanProps } = resolvedProps;
       const { renderToString } = await import("react-dom/server");
       const mod = await sectionLoader();
-      const sectionHtml = renderToString(createElement(mod.default, cleanProps));
+      const element = createElement(mod.default, cleanProps);
+      const Wrapper = getPreviewWrapper();
+      const wrapped = Wrapper ? createElement(Wrapper, null, element) : element;
+      const sectionHtml = renderToString(wrapped);
       return new Response(wrapInHtmlShell(sectionHtml), {
         status: 200,
         headers: { "Content-Type": "text/html; charset=utf-8" },

package/src/admin/setup.ts

@@ -25,6 +25,38 @@ let themeName = "";
 let bodyClass = "";
 let htmlLang = "en";
 
+/**
+ * Optional React component that wraps section renders in admin previews.
+ * Use this to provide context that sections depend on (Router, QueryClient, etc.)
+ * without which renderToString would crash.
+ *
+ * The wrapper receives `{ children }` and should render them inside the
+ * necessary providers.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let previewWrapperComponent: any = null;
+
+/**
+ * Register a wrapper component for admin preview renders.
+ *
+ * @example
+ * ```ts
+ * // In site's setup.ts:
+ * import { setPreviewWrapper } from "@decocms/start/admin/setup";
+ * import { PreviewProviders } from "./components/PreviewProviders";
+ * setPreviewWrapper(PreviewProviders);
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function setPreviewWrapper(wrapper: any) {
+  previewWrapperComponent = wrapper;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function getPreviewWrapper(): any {
+  return previewWrapperComponent;
+}
+
 export function setRenderShell(opts: {
   css?: string;
   fonts?: string[];