@decocms/nextjs 7.16.6 → 7.16.7

package/README.md

@@ -1,7 +1,7 @@
 # `@decocms/nextjs`
 
 Deco framework binding for Next.js App Router — the Next.js sibling of
-`@decocms/tanstack`. Three surfaces, composed together:
+`@decocms/tanstack`. Four surfaces, composed together:
 
 - **`@decocms/nextjs/config`** — `withDeco(nextConfig)`, a `next.config`
   wrapper that adds the rewrites and `transpilePackages` Deco's admin
@@ -9,12 +9,15 @@ Deco framework binding for Next.js App Router — the Next.js sibling of
 - **`@decocms/nextjs/routeHandlers`** — `createDecoRouteHandlers({ setup })`,
   a single catch-all dispatcher for the whole Studio admin protocol
   (decofile read/reload, meta schema, invoke, live previews).
+- **`@decocms/nextjs`** — `createDecoPreviewPage({ setup })`, an App Router
+  Server Component that renders live previews through Next's RSC pipeline,
+  including sections marked with `"use client"`.
 - **`@decocms/nextjs/setup`** — `createNextSetup(options)`, a one-call site
   bootstrap: the Next.js analogue of Vite's
   `createSiteSetup` + `createAdminSetup` + `import.meta.glob`.
 
 This document is the complete recipe a new Next.js site follows to wire all
-three together. Every code block below is meant to be copied, not
+all four together. Every code block below is meant to be copied, not
 paraphrased.
 
 ## Install
@@ -78,13 +81,50 @@ import { ensureSetup } from "../../../deco/setup";
 
 export const dynamic = "force-dynamic";
 
-export const { GET, POST, OPTIONS } = createDecoRouteHandlers({ setup: ensureSetup });
+export const { GET, POST, OPTIONS } = createDecoRouteHandlers({
+  setup: ensureSetup,
+});
 ```
 
 `dynamic = "force-dynamic"` is required — this route must never be
 statically cached (decofile reloads, invoke calls, and previews all need a
 fresh response per request).
 
+### The RSC preview page
+
+Mount `createDecoPreviewPage` at the framework-owned `/deco/preview` path.
+This path is intentionally not configurable: preview GET requests are always
+redirected from the catch-all route to this App Router page, with the query
+string preserved. Other admin requests, including `POST /deco/render`, remain
+on the catch-all handler.
+
+```tsx
+// src/app/deco/preview/[[...path]]/page.tsx
+import { createDecoPreviewPage } from "@decocms/nextjs";
+import { ensureSetup } from "../../../../deco/setup";
+
+export const dynamic = "force-dynamic";
+
+export default createDecoPreviewPage({ setup: ensureSetup });
+```
+
+The page boundary is essential for Client Components. A route handler can
+produce plain HTML with `react-dom/server`, but that renderer cannot execute
+the client-reference proxies Next creates for modules marked
+`"use client"`. An App Router page is rendered by Next's React Server
+Components pipeline, so it can render a server section tree containing
+Client Components and preserve their hydration metadata.
+
+Do not work around this error by removing `"use client"` from interactive
+components. Keep sections and wrappers as Server Components when they only
+render markup, but retain a Client Component boundary wherever hooks, event
+handlers, browser APIs, or client-only context are required. The RSC preview
+page exists so those two kinds of component can compose exactly as they do in
+the storefront.
+
+Importing the root barrel is correct in this `page.tsx`; the subpath-only
+rule below applies specifically to `route.ts` files.
+
 ### Route-handler import rule: subpaths, never the root barrel
 
 **Always import from `@decocms/nextjs/routeHandlers` (or `/config`,
@@ -189,7 +229,7 @@ successful bootstrap is cached for the life of the warm serverless
 instance; a *rejected* bootstrap clears the memo so the next call retries
 from scratch (the triggering call still rejects with the original error).
 
-Two call sites need `ensureSetup()`:
+Three call sites need `ensureSetup()`:
 
 1. **The catch-all route** (above) passes it as `{ setup: ensureSetup }` —
    `createDecoRouteHandlers` awaits it before dispatching every admin
@@ -211,6 +251,9 @@ Two call sites need `ensureSetup()`:
 
    (`app/layout.tsx` is a Server Component, not a route handler, so it's
    fine to import the root barrel here — see the rule above.)
+3. **The RSC preview page** passes it to `createDecoPreviewPage`, as shown
+   above. The setup function is memoized, so these call sites share one
+   successful bootstrap per warm process.
 
 ### `NextSetupOptions` at a glance
 
@@ -317,7 +360,8 @@ implementation file) can opt into these, each read as a literal
 ## Verifying your setup
 
 `examples/nextjs-smoke` in this monorepo is a minimal, real Next.js App
-Router build exercising all three surfaces end to end — `withDeco` rewrites,
-the catch-all route, `createNextSetup`, and a resolved page render. Use it
-as a working reference if any of the above doesn't compose the way you
-expect.
+Router build exercising all four surfaces end to end — `withDeco` rewrites,
+the catch-all route, the RSC preview page, `createNextSetup`, and a resolved
+page render. Its preview fixture is a real interactive Client Component, so
+the build also guards the server/client boundary described above. Use it as
+a working reference if any of the above doesn't compose the way you expect.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/nextjs",
-  "version": "7.16.6",
+  "version": "7.16.7",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -28,8 +28,8 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.16.6",
-    "@decocms/blocks-admin": "7.16.6"
+    "@decocms/blocks": "7.16.7",
+    "@decocms/blocks-admin": "7.16.7"
   },
   "peerDependencies": {
     "next": ">=15.0.0",

package/src/createDecoPreviewPage.test.tsx

@@ -0,0 +1,71 @@
+// @vitest-environment node
+
+import { registerSection, setBlocks } from "@decocms/blocks/cms";
+import { setRenderShell } from "@decocms/blocks-admin";
+import { renderToString } from "react-dom/server";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { createDecoPreviewPage } from "./createDecoPreviewPage";
+import * as nextjs from "./index";
+
+vi.mock("next/headers", () => ({
+  headers: vi.fn(
+    async () =>
+      new Headers({
+        host: "store.test",
+        "x-forwarded-proto": "https",
+        "user-agent": "preview-test",
+      }),
+  ),
+}));
+
+const HERO = "site/sections/PreviewHero.tsx";
+
+beforeEach(() => {
+  setBlocks({
+    "Preview Hero": { __resolveType: HERO, label: "rsc" },
+  });
+  registerSection(HERO, async () => ({
+    default: ({ label }: { label?: string }) => <h1>{`hero-${label}`}</h1>,
+  }));
+  setRenderShell({
+    css: "/preview.css",
+    fonts: ["/font.css"],
+    theme: "light",
+    bodyClass: "preview-body",
+  });
+});
+
+describe("createDecoPreviewPage", () => {
+  it("is exposed by the Next.js binding", () => {
+    expect((nextjs as Record<string, unknown>).createDecoPreviewPage).toBeTypeOf("function");
+  });
+
+  it("resolves and renders a section through the RSC-aware SectionRenderer", async () => {
+    const setup = vi.fn(async () => {});
+    const Page = createDecoPreviewPage({ setup });
+    const element = await Page({
+      params: Promise.resolve({ path: ["Preview Hero"] }),
+      searchParams: Promise.resolve({ deviceHint: "desktop" }),
+    });
+    const html = renderToString(element);
+
+    expect(setup).toHaveBeenCalledOnce();
+    expect(html).toContain("hero-rsc");
+    expect(html).toContain('data-manifest-key="site/sections/PreviewHero.tsx"');
+    expect(html).toContain('href="/preview.css"');
+    expect(html).toContain('href="/font.css"');
+    expect(html).toContain('data-theme="light"');
+    expect(html).toContain("preview-body");
+    expect(html).toContain("editor::inject");
+  });
+
+  it("renders a visible diagnostic for an unknown section", async () => {
+    const Page = createDecoPreviewPage();
+    const element = await Page({
+      params: Promise.resolve({ path: ["Missing"] }),
+      searchParams: Promise.resolve({}),
+    });
+
+    expect(renderToString(element)).toContain("Unknown section: Missing");
+  });
+});

package/src/createDecoPreviewPage.tsx

@@ -0,0 +1,108 @@
+import { LIVE_CONTROLS_SCRIPT, resolvePreviewRequest } from "@decocms/blocks-admin";
+import { getPreviewWrapper, getRenderShellConfig } from "@decocms/blocks-admin/admin/setup";
+import { headers } from "next/headers";
+import { cloneElement, createElement, type ReactElement, type ReactNode } from "react";
+import { SectionRenderer } from "./SectionRenderer";
+
+export interface CreateDecoPreviewPageOptions {
+  setup?: () => Promise<void>;
+}
+
+export interface DecoPreviewPageProps {
+  params: Promise<{ path?: string[] }>;
+  searchParams: Promise<Record<string, string | string[] | undefined>>;
+}
+
+function appendSearchParams(
+  target: URLSearchParams,
+  source: Record<string, string | string[] | undefined>,
+) {
+  for (const [key, value] of Object.entries(source)) {
+    if (Array.isArray(value)) {
+      for (const item of value) target.append(key, item);
+    } else if (value !== undefined) {
+      target.set(key, value);
+    }
+  }
+}
+
+async function buildPreviewRequest(props: DecoPreviewPageProps): Promise<Request> {
+  const [params, searchParams, requestHeaders] = await Promise.all([
+    props.params,
+    props.searchParams,
+    headers(),
+  ]);
+  const host = requestHeaders.get("x-forwarded-host") ?? requestHeaders.get("host") ?? "localhost";
+  const protocol = requestHeaders.get("x-forwarded-proto") ?? "http";
+  const encodedPath = (params.path ?? []).map(encodeURIComponent).join("/");
+  const url = new URL(`/live/previews/${encodedPath}`, `${protocol}://${host}`);
+  appendSearchParams(url.searchParams, searchParams);
+  return new Request(url, { headers: new Headers(requestHeaders) });
+}
+
+function PreviewResources() {
+  const { cssHref, fontHrefs } = getRenderShellConfig();
+  return (
+    <>
+      {fontHrefs.map((href) => (
+        <link key={href} rel="stylesheet" href={href} />
+      ))}
+      {cssHref ? <link rel="stylesheet" href={cssHref} /> : null}
+    </>
+  );
+}
+
+function PreviewFrame({ children }: { children: ReactNode }) {
+  const { themeName, bodyClass } = getRenderShellConfig();
+  const Wrapper = getPreviewWrapper();
+  const content = Wrapper ? createElement(Wrapper, null, children) : children;
+
+  return (
+    <>
+      <PreviewResources />
+      <div data-theme={themeName || "light"} className={bodyClass || undefined}>
+        {content}
+      </div>
+      <script dangerouslySetInnerHTML={{ __html: LIVE_CONTROLS_SCRIPT }} />
+    </>
+  );
+}
+
+function PreviewDiagnostic({ children }: { children: ReactNode }) {
+  return <div style={{ padding: 20, color: "red" }}>{children}</div>;
+}
+
+export function createDecoPreviewPage(options: CreateDecoPreviewPageOptions = {}) {
+  return async function DecoPreviewPage(props: DecoPreviewPageProps) {
+    await options.setup?.();
+
+    try {
+      const request = await buildPreviewRequest(props);
+      const resolution = await resolvePreviewRequest(request);
+      if (resolution.type === "unknown") {
+        return (
+          <PreviewFrame>
+            <PreviewDiagnostic>{`Unknown section: ${resolution.component}`}</PreviewDiagnostic>
+          </PreviewFrame>
+        );
+      }
+
+      const rendered = await Promise.all(
+        resolution.sections.map(async (section, index): Promise<ReactElement | null> => {
+          const element = await SectionRenderer({ resolved: section });
+          return element
+            ? cloneElement(element, { key: `${section.key}-${section.index ?? index}` })
+            : null;
+        }),
+      );
+
+      return <PreviewFrame>{rendered}</PreviewFrame>;
+    } catch (error) {
+      return (
+        <PreviewFrame>
+          <PreviewDiagnostic>{`Render error: ${(error as Error).message}`}</PreviewDiagnostic>
+        </PreviewFrame>
+      );
+    }
+  };
+}

package/src/index.ts

@@ -1,8 +1,12 @@
+export { ClientOnlySection } from "./ClientOnlySection";
 export { createDecoPage } from "./createDecoPage";
-export { DecoRootLayout, type DecoRootLayoutProps } from "./DecoRootLayout";
+export {
+  type CreateDecoPreviewPageOptions,
+  createDecoPreviewPage,
+  type DecoPreviewPageProps,
+} from "./createDecoPreviewPage";
 export { DecoPageRenderer } from "./DecoPageRenderer";
-export { SectionRenderer } from "./SectionRenderer";
-export { ClientOnlySection } from "./ClientOnlySection";
+export { DecoRootLayout, type DecoRootLayoutProps } from "./DecoRootLayout";
 export { DeferredSectionBoundary } from "./DeferredSection";
 export {
   decofileGET,
@@ -12,3 +16,4 @@ export {
   renderGET,
   renderPOST,
 } from "./routeHandlers";
+export { SectionRenderer } from "./SectionRenderer";

package/src/routeHandlers.test.ts

@@ -67,12 +67,44 @@ describe("createDecoRouteHandlers", () => {
     expect(mocks.handleInvoke).toHaveBeenCalled();
   });
 
-  it("rebuilds /deco/previews/* URLs to the /live/previews/* prefix handleRender parses", async () => {
+  it("redirects preview GETs to the fixed RSC page and preserves the path and query", async () => {
     const { GET } = createDecoRouteHandlers();
-    const res = await GET(new Request("http://x/deco/previews/pages-Home-123?props=x"));
-    expect(await res.text()).toBe("/live/previews/pages-Home-123");
-    const calledUrl = new URL(mocks.handleRender.mock.calls[0][0].url);
-    expect(calledUrl.searchParams.get("props")).toBe("x");
+    const res = await GET(
+      new Request("http://x/deco/previews/pages-Home-123?props=x&deviceHint=mobile"),
+    );
+
+    expect(res.status).toBe(307);
+    expect(res.headers.get("location")).toBe(
+      "http://x/deco/preview/pages-Home-123?props=x&deviceHint=mobile",
+    );
+    expect(mocks.handleRender).not.toHaveBeenCalled();
+  });
+
+  it("redirects the public /live/previews path to the fixed RSC page", async () => {
+    const { GET } = createDecoRouteHandlers();
+    const res = await GET(
+      new Request("http://x/live/previews/site/sections/Hero.tsx?deviceHint=desktop"),
+    );
+
+    expect(res.status).toBe(307);
+    expect(res.headers.get("location")).toBe(
+      "http://x/deco/preview/site/sections/Hero.tsx?deviceHint=desktop",
+    );
+    expect(mocks.handleRender).not.toHaveBeenCalled();
+  });
+
+  it("keeps preview POSTs on handleRender", async () => {
+    const { POST } = createDecoRouteHandlers();
+    const res = await POST(
+      new Request("http://x/deco/previews/pages-Home-123", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ hello: "world" }),
+      }),
+    );
+
+    expect(res.status).toBe(200);
+    expect(mocks.handleRender).toHaveBeenCalledOnce();
   });
 
   it("forwards a POST body through the /deco/previews/* URL rebuild (Request-as-init carries the body stream)", async () => {
@@ -135,12 +167,12 @@ describe("createDecoRouteHandlers", () => {
     expect(mocks.handleMeta).not.toHaveBeenCalled();
   });
 
-  it("routes the rewrite-source /live/previews/* path straight through to handleRender with the prefix intact", async () => {
+  it("redirects the rewrite-source /live/previews/* path to the fixed RSC page", async () => {
     const { GET } = createDecoRouteHandlers();
     const res = await GET(new Request("http://x/live/previews/pages-Home-123?props=x"));
-    expect(await res.text()).toBe("/live/previews/pages-Home-123");
-    const calledUrl = new URL(mocks.handleRender.mock.calls[0][0].url);
-    expect(calledUrl.searchParams.get("props")).toBe("x");
+    expect(res.status).toBe(307);
+    expect(res.headers.get("location")).toBe("http://x/deco/preview/pages-Home-123?props=x");
+    expect(mocks.handleRender).not.toHaveBeenCalled();
   });
 
   it("405s GET /deco/invoke/* with Allow: POST (CSRF protection — see comment on the invoke branch)", async () => {

package/src/routeHandlers.ts

@@ -93,6 +93,8 @@ export interface DecoRouteHandlersOptions {
   setup?: () => Promise<void>;
 }
 
+const PREVIEW_PAGE_PATH = "/deco/preview";
+
 /**
  * Single catch-all dispatcher for the whole Studio admin protocol. Mount
  * at `app/deco/[[...deco]]/route.ts` and wrap next.config with
@@ -104,7 +106,9 @@ export interface DecoRouteHandlersOptions {
  * import { createDecoRouteHandlers } from "@decocms/nextjs/routeHandlers";
  * import { ensureSetup } from "../../../deco/setup";
  * export const dynamic = "force-dynamic";
- * export const { GET, POST, OPTIONS } = createDecoRouteHandlers({ setup: ensureSetup });
+ * export const { GET, POST, OPTIONS } = createDecoRouteHandlers({
+ *   setup: ensureSetup,
+ * });
  * ```
  *
  * `resolveAction` accepts BOTH the rewrite's public source path (e.g.
@@ -184,6 +188,13 @@ export function createDecoRouteHandlers(options: DecoRouteHandlersOptions = {}):
       return handleInvoke(request);
     }
     if (action === "previews" || action.startsWith("previews/")) {
+      if (request.method === "GET") {
+        const rest = action === "previews" ? "" : action.slice("previews/".length);
+        const target = new URL(url);
+        target.pathname = rest ? `${PREVIEW_PAGE_PATH}/${rest}` : PREVIEW_PAGE_PATH;
+        return Response.redirect(target, 307);
+      }
+
       // handleRender parses the literal "/live/previews/" prefix.
       // `resolveAction` above already normalizes BOTH a direct
       // `/deco/previews/*` hit and a rewritten `/live/previews/*` hit down