@decocms/nextjs 7.28.1 → 8.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/nextjs",
-  "version": "7.28.1",
+  "version": "8.0.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -19,7 +19,8 @@
     "./config": {
       "types": "./src/config.d.cts",
       "default": "./src/config.cjs"
-    }
+    },
+    "./middleware": "./src/draftMiddleware.ts"
   },
   "scripts": {
     "build": "tsc",
@@ -28,8 +29,8 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.28.1",
-    "@decocms/blocks-admin": "7.28.1"
+    "@decocms/blocks": "8.0.0",
+    "@decocms/blocks-admin": "8.0.0"
   },
   "peerDependencies": {
     "next": ">=15.0.0",

package/src/DecoPageRenderer.test.tsx

@@ -1,6 +1,6 @@
+import { registerSectionsSync } from "@decocms/blocks/cms";
 import { renderToString } from "react-dom/server";
 import { describe, expect, it } from "vitest";
-import { registerSectionsSync } from "@decocms/blocks/cms";
 import { DecoPageRenderer } from "./DecoPageRenderer";
 
 function Hero({ label }: { label?: string }) {
@@ -16,8 +16,18 @@ describe("DecoPageRenderer (next)", () => {
 
     const element = await DecoPageRenderer({
       sections: [
-        { key: "site/sections/NextPageA.tsx", component: "site/sections/NextPageA.tsx", props: { label: "first" }, index: 0 } as any,
-        { key: "site/sections/NextPageB.tsx", component: "site/sections/NextPageB.tsx", props: { label: "second" }, index: 1 } as any,
+        {
+          key: "site/sections/NextPageA.tsx",
+          component: "site/sections/NextPageA.tsx",
+          props: { label: "first" },
+          index: 0,
+        } as any,
+        {
+          key: "site/sections/NextPageB.tsx",
+          component: "site/sections/NextPageB.tsx",
+          props: { label: "second" },
+          index: 1,
+        } as any,
       ],
       pagePath: "/",
     });

package/src/DecoPageRenderer.tsx

@@ -1,8 +1,8 @@
 import type { DeferredSection, ResolvedSection } from "@decocms/blocks/cms";
 import { resolveDeferredSection } from "@decocms/blocks/cms";
-import { SectionRenderer } from "./SectionRenderer";
-import { DeferredSectionBoundary } from "./DeferredSection";
 import { cloneElement, type ReactElement, type ReactNode } from "react";
+import { DeferredSectionBoundary } from "./DeferredSection";
+import { SectionRenderer } from "./SectionRenderer";
 
 interface DecoPageRendererProps {
   sections: ResolvedSection[];
@@ -19,7 +19,9 @@ type PageItem =
 
 function mergeSections(resolved: ResolvedSection[], deferred: DeferredSection[]): PageItem[] {
   const items: PageItem[] = [];
-  resolved.forEach((section, i) => items.push({ type: "eager", section, sort: section.index ?? i }));
+  resolved.forEach((section, i) =>
+    items.push({ type: "eager", section, sort: section.index ?? i }),
+  );
   for (const d of deferred) items.push({ type: "deferred", deferred: d, sort: d.index });
   items.sort((a, b) => a.sort - b.sort);
   return items;
@@ -54,10 +56,12 @@ export async function DecoPageRenderer({
   for (const d of deferredSections) {
     deferredPromises.set(
       d.index,
-      resolveDeferredSection(d.component, d.rawProps ?? {}, pagePath, matcherCtx).then((resolved) => {
-        if (!resolved) return null;
-        return { ...resolved, index: d.index };
-      }),
+      resolveDeferredSection(d.component, d.rawProps ?? {}, pagePath, matcherCtx).then(
+        (resolved) => {
+          if (!resolved) return null;
+          return { ...resolved, index: d.index };
+        },
+      ),
     );
   }
 

package/src/DecoRootLayout.tsx

@@ -1,6 +1,6 @@
-import type { ReactNode } from "react";
 import { LiveControls } from "@decocms/blocks/hooks";
 import { ANALYTICS_SCRIPT } from "@decocms/blocks/sdk/analytics";
+import type { ReactNode } from "react";
 
 function buildDecoEventsBootstrap(account?: string): string {
   const accountJson = JSON.stringify(account ?? "");

package/src/DeferredSection.test.tsx

@@ -1,6 +1,6 @@
+import { registerSectionsSync } from "@decocms/blocks/cms";
 import { renderToString } from "react-dom/server";
 import { describe, expect, it } from "vitest";
-import { registerSectionsSync } from "@decocms/blocks/cms";
 import { DeferredSectionBoundary } from "./DeferredSection";
 
 function Hero({ label }: { label?: string }) {

package/src/DeferredSection.tsx

@@ -1,6 +1,6 @@
-import { Suspense, type ReactNode } from "react";
 import type { DeferredSection, ResolvedSection } from "@decocms/blocks/cms";
 import { SectionErrorBoundary } from "@decocms/blocks/hooks";
+import { type ReactNode, Suspense } from "react";
 import { SectionRenderer } from "./SectionRenderer";
 
 interface DeferredSectionBoundaryProps {

package/src/DraftPreviewBadge.render.test.tsx

@@ -0,0 +1,16 @@
+import { renderToString } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+
+import { DraftPreviewBadge } from "./DraftPreviewBadge";
+
+describe("DraftPreviewBadge (render)", () => {
+  it("surfaces the preview-mode label so a reviewer can't mistake a draft for live", () => {
+    const html = renderToString(<DraftPreviewBadge pointer="fila.vtex.app@v1" />);
+    expect(html).toContain("Preview mode");
+  });
+
+  it("embeds the deco mark inline (no external asset that could 404 on a consumer site)", () => {
+    const html = renderToString(<DraftPreviewBadge pointer="fila.vtex.app@v1" />);
+    expect(html).toContain("data:image/png;base64,");
+  });
+});

package/src/DraftPreviewBadge.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+
+import { buildExitUrl, buildShareUrl } from "./DraftPreviewBadge";
+
+describe("buildShareUrl", () => {
+  it("pins the exact draft version so a recipient sees the same working tree", () => {
+    expect(buildShareUrl("https://fila.vtex.app/pdp/shoe", "abc.localhost:60534@v7")).toBe(
+      "https://fila.vtex.app/pdp/shoe?__draft=abc.localhost%3A60534%40v7",
+    );
+  });
+
+  it("preserves existing query params, only setting the draft token", () => {
+    expect(buildShareUrl("https://fila.vtex.app/plp?sort=price", "h@v1")).toBe(
+      "https://fila.vtex.app/plp?sort=price&__draft=h%40v1",
+    );
+  });
+
+  it("replaces a stale token already in the URL rather than appending a second", () => {
+    expect(buildShareUrl("https://fila.vtex.app/p?__draft=h@old", "h@new")).toBe(
+      "https://fila.vtex.app/p?__draft=h%40new",
+    );
+  });
+});
+
+describe("buildExitUrl", () => {
+  it("sets the ?__draft=off exit sentinel", () => {
+    expect(buildExitUrl("https://fila.vtex.app/pdp/shoe")).toBe(
+      "https://fila.vtex.app/pdp/shoe?__draft=off",
+    );
+  });
+
+  it("overrides an active token with off (leaves preview from anywhere)", () => {
+    expect(buildExitUrl("https://fila.vtex.app/p?__draft=h@v1")).toBe(
+      "https://fila.vtex.app/p?__draft=off",
+    );
+  });
+});

package/src/DraftPreviewBadge.tsx

@@ -0,0 +1,252 @@
+"use client";
+
+/**
+ * Preview-mode indicator.
+ *
+ * The draft-preview flow (see `draft.ts`) carries the pointer in a cookie
+ * across in-preview navigation, so after the first click the URL no longer
+ * shows `?__draft=` — a reviewer can forget they are looking at unpublished
+ * content and mistake it for what is live. This badge is the always-on signal:
+ * whenever a draft is bound it floats over the page, and clicking it offers the
+ * two things a reviewer actually needs — leave preview, or hand the exact draft
+ * version to someone else.
+ *
+ * Deliberately self-contained: `"use client"`, inline styles (no dependency on
+ * the host site's CSS/Tailwind), and a very high z-index, so it renders the
+ * same on any consumer site. Only mounted when a draft is active
+ * (`DraftPreviewIndicator` gates it), so it never costs ordinary traffic.
+ */
+import { type ReactNode, useCallback, useEffect, useRef, useState } from "react";
+import { DECO_MARK_DATA_URI } from "./decoMark";
+import { DRAFT_PARAM } from "./draftConstants";
+
+export interface DraftPreviewBadgeProps {
+  /** The `<host>@<version>` token this render is bound to. */
+  pointer: string;
+}
+
+/**
+ * URL that re-enters this exact draft version — what "Share Preview Link"
+ * copies. Pins the version (the token carries the content ETag), so the
+ * recipient sees the same working-tree state, not merely "some draft".
+ *
+ * Pure and exported for tests: builds off a full href so it needs no DOM.
+ */
+export function buildShareUrl(href: string, pointer: string): string {
+  const url = new URL(href);
+  url.searchParams.set(DRAFT_PARAM, pointer);
+  return url.toString();
+}
+
+/**
+ * URL that leaves preview mode — `?__draft=off`, the exit sentinel the
+ * middleware/page pair understands (it clears the cookie and renders
+ * published). Pure and exported for tests.
+ */
+export function buildExitUrl(href: string): string {
+  const url = new URL(href);
+  url.searchParams.set(DRAFT_PARAM, "off");
+  return url.toString();
+}
+
+const DECO_GREEN = "#0b3d1e";
+/** Toast background — the deco lime. Text sits on it in dark green for contrast. */
+const DECO_LIME = "#d0ec1a";
+
+/** Leaving preview: an arrow back to the published site. */
+function ExitIcon() {
+  return (
+    <svg
+      width={14}
+      height={14}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M19 12H5" />
+      <path d="M12 19l-7-7 7-7" />
+    </svg>
+  );
+}
+
+/** Sharing the draft: the classic three-node share glyph. */
+function ShareIcon() {
+  return (
+    <svg
+      width={14}
+      height={14}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <circle cx={18} cy={5} r={3} />
+      <circle cx={6} cy={12} r={3} />
+      <circle cx={18} cy={19} r={3} />
+      <path d="M8.59 13.51l6.83 3.98" />
+      <path d="M15.41 6.51l-6.82 3.98" />
+    </svg>
+  );
+}
+
+export function DraftPreviewBadge({ pointer }: DraftPreviewBadgeProps) {
+  const [open, setOpen] = useState(false);
+  const [copied, setCopied] = useState(false);
+  const rootRef = useRef<HTMLDivElement>(null);
+
+  // Dismiss on outside click or Escape — standard popover behaviour, and it
+  // keeps the badge from trapping focus on a reviewer's own page.
+  useEffect(() => {
+    if (!open) return;
+    const onPointerDown = (e: MouseEvent) => {
+      if (rootRef.current && !rootRef.current.contains(e.target as Node)) setOpen(false);
+    };
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key === "Escape") setOpen(false);
+    };
+    document.addEventListener("mousedown", onPointerDown);
+    document.addEventListener("keydown", onKeyDown);
+    return () => {
+      document.removeEventListener("mousedown", onPointerDown);
+      document.removeEventListener("keydown", onKeyDown);
+    };
+  }, [open]);
+
+  const exitPreview = useCallback(() => {
+    window.location.href = buildExitUrl(window.location.href);
+  }, []);
+
+  const sharePreviewLink = useCallback(async () => {
+    const link = buildShareUrl(window.location.href, pointer);
+    try {
+      await navigator.clipboard.writeText(link);
+      setCopied(true);
+      window.setTimeout(() => setCopied(false), 2000);
+    } catch {
+      // Clipboard blocked (insecure context / permissions): fall back to a
+      // prompt so the reviewer can still copy the link by hand rather than
+      // silently doing nothing.
+      window.prompt("Copy preview link:", link);
+    }
+  }, [pointer]);
+
+  return (
+    <div
+      ref={rootRef}
+      data-deco-preview-badge=""
+      style={{
+        position: "fixed",
+        bottom: 16,
+        left: 16,
+        zIndex: 2147483647,
+        fontFamily:
+          "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif",
+        fontSize: 13,
+        lineHeight: 1.4,
+      }}
+    >
+      {open ? (
+        <div
+          role="menu"
+          style={{
+            position: "absolute",
+            bottom: "calc(100% + 8px)",
+            left: 0,
+            minWidth: 200,
+            background: "#fff",
+            color: "#1a1a1a",
+            borderRadius: 12,
+            boxShadow: "0 8px 30px rgba(0,0,0,0.18), 0 0 0 1px rgba(0,0,0,0.05)",
+            overflow: "hidden",
+          }}
+        >
+          <MenuItem onClick={exitPreview} label="Exit preview" icon={<ExitIcon />} />
+          <div style={{ height: 1, background: "rgba(0,0,0,0.07)" }} />
+          <MenuItem
+            onClick={sharePreviewLink}
+            label={copied ? "Copied!" : "Share preview"}
+            icon={<ShareIcon />}
+          />
+        </div>
+      ) : null}
+
+      <button
+        type="button"
+        aria-expanded={open}
+        aria-label="Preview mode"
+        onClick={() => setOpen((v) => !v)}
+        style={{
+          display: "inline-flex",
+          alignItems: "center",
+          gap: 8,
+          padding: "7px 12px 7px 8px",
+          background: DECO_LIME,
+          color: DECO_GREEN,
+          border: "none",
+          borderRadius: 9999,
+          cursor: "pointer",
+          fontSize: 13,
+          fontWeight: 600,
+          boxShadow: "0 4px 14px rgba(0,0,0,0.25)",
+        }}
+      >
+        <img
+          src={DECO_MARK_DATA_URI}
+          alt=""
+          width={18}
+          height={18}
+          style={{ display: "block", borderRadius: 4 }}
+        />
+        <span>Preview mode</span>
+      </button>
+    </div>
+  );
+}
+
+function MenuItem({
+  onClick,
+  label,
+  icon,
+}: {
+  onClick: () => void;
+  label: string;
+  icon: ReactNode;
+}) {
+  return (
+    <button
+      type="button"
+      role="menuitem"
+      onClick={onClick}
+      style={{
+        display: "flex",
+        alignItems: "center",
+        gap: 10,
+        width: "100%",
+        textAlign: "left",
+        padding: "10px 14px",
+        background: "transparent",
+        border: "none",
+        color: "inherit",
+        cursor: "pointer",
+        fontSize: 13,
+        whiteSpace: "nowrap",
+      }}
+      onMouseEnter={(e) => {
+        e.currentTarget.style.background = "rgba(0,0,0,0.05)";
+      }}
+      onMouseLeave={(e) => {
+        e.currentTarget.style.background = "transparent";
+      }}
+    >
+      <span style={{ display: "inline-flex", flexShrink: 0, color: DECO_GREEN }}>{icon}</span>
+      <span>{label}</span>
+    </button>
+  );
+}

package/src/DraftPreviewIndicator.tsx

@@ -0,0 +1,22 @@
+/**
+ * Server-side gate for the preview-mode badge.
+ *
+ * A Server Component (no `"use client"`) so it can read the request-scoped
+ * draft pointer via `getActiveDraftPointer()` and mount the client badge ONLY
+ * when a draft is actually bound — an unconfigured/published request renders
+ * nothing at all.
+ *
+ * Placement rule (inherited from `ensureDraft`): render this INSIDE the page
+ * subtree, after `ensureDraft` has been awaited — never from a layout, whose
+ * children render concurrently with the page that fills the slot. Sites using
+ * `createDecoPage` get it wired automatically; hand-rolled routes drop
+ * `<DraftPreviewIndicator />` at the end of their page.
+ */
+import { DraftPreviewBadge } from "./DraftPreviewBadge";
+import { getActiveDraftPointer } from "./draft";
+
+export function DraftPreviewIndicator() {
+  const pointer = getActiveDraftPointer();
+  if (!pointer) return null;
+  return <DraftPreviewBadge pointer={pointer} />;
+}

package/src/SectionRenderer.test.tsx

@@ -1,6 +1,6 @@
+import { registerSection, registerSections, registerSectionsSync } from "@decocms/blocks/cms";
 import { renderToString } from "react-dom/server";
 import { beforeEach, describe, expect, it, vi } from "vitest";
-import { registerSection, registerSections, registerSectionsSync } from "@decocms/blocks/cms";
 import { SectionRenderer } from "./SectionRenderer";
 
 function Hero({ label }: { label?: string }) {

package/src/SectionRenderer.tsx

@@ -1,11 +1,7 @@
-import { createElement, type ReactNode } from "react";
-import {
-  getSection,
-  getSectionOptions,
-  getSyncComponent,
-} from "@decocms/blocks/cms";
 import type { ResolvedSection } from "@decocms/blocks/cms";
+import { getSection, getSectionOptions, getSyncComponent } from "@decocms/blocks/cms";
 import { SectionErrorBoundary } from "@decocms/blocks/hooks";
+import { createElement, type ReactNode } from "react";
 import { ClientOnlySection } from "./ClientOnlySection";
 
 interface SectionRendererProps {

package/src/config.cjs

@@ -12,6 +12,7 @@
  *    (`app/deco/[[...deco]]/route.ts` + createDecoRouteHandlers) serves
  *    the whole protocol.
  * 2. transpilePackages for the raw-TS @decocms packages.
+ * 3. Response headers that keep a draft-preview render out of every cache.
  */
 const DECO_REWRITES = [
   { source: "/.decofile", destination: "/deco/decofile" },
@@ -21,8 +22,56 @@ const DECO_REWRITES = [
 
 const DECO_TRANSPILE = ["@decocms/blocks", "@decocms/blocks-admin", "@decocms/nextjs"];
 
+/**
+ * A draft render must never be cached or indexed: with the pointer in a cookie
+ * it shares a URL with the published page, so a shared cache keyed on URL alone
+ * would serve unpublished content to a real visitor.
+ *
+ * Two rules, not one: `has` entries within a rule are ANDed, and the two
+ * signals never coincide. On ENTRY the pointer is in the query and the cookie
+ * has not been set yet (middleware sets it in the response); on every
+ * navigation after that it is the cookie and the query is gone.
+ *
+ * MEASURED LIMIT — do not assume `no-store` is in force. On a *dynamic* App
+ * Router response Next reserves `Cache-Control` and `Vary` and overwrites
+ * whatever we set, from here AND from middleware: the wire shows
+ * `Cache-Control: no-cache, must-revalidate` and
+ * `Vary: rsc, next-router-state-tree, …`. Verified that these rules do match
+ * (a marker header on the same rules came through on both signals and was
+ * correctly absent otherwise) — it is those two header names specifically that
+ * Next owns. `X-Robots-Tag` does get through.
+ *
+ * Why that is still safe: `no-cache` is not "don't cache", it is "never reuse
+ * without revalidating with the origin", so a compliant shared cache cannot
+ * serve a stored draft to a different visitor — it has to ask us first, and we
+ * answer per-request. That also covers the loss of `Vary: Cookie`. The residual
+ * risk is a cache that ignores `no-cache`; closing that needs a CDN-level rule,
+ * which is a deployment concern rather than something this package can set.
+ * `Cache-Control`/`Vary` are kept here so the intent is explicit and so they
+ * apply anywhere Next is not overriding them.
+ */
+const DRAFT_NO_STORE_HEADERS = [
+  { key: "Cache-Control", value: "no-store, private" },
+  { key: "Vary", value: "Cookie" },
+  { key: "X-Robots-Tag", value: "noindex, nofollow" },
+];
+
+const DECO_DRAFT_HEADERS = [
+  {
+    source: "/:path*",
+    has: [{ type: "query", key: "__draft" }],
+    headers: DRAFT_NO_STORE_HEADERS,
+  },
+  {
+    source: "/:path*",
+    has: [{ type: "cookie", key: "__deco_draft" }],
+    headers: DRAFT_NO_STORE_HEADERS,
+  },
+];
+
 function withDeco(nextConfig = {}) {
   const userRewrites = nextConfig.rewrites;
+  const userHeaders = nextConfig.headers;
   return {
     ...nextConfig,
     transpilePackages: [...new Set([...(nextConfig.transpilePackages ?? []), ...DECO_TRANSPILE])],
@@ -31,7 +80,13 @@ function withDeco(nextConfig = {}) {
       if (Array.isArray(user)) return [...DECO_REWRITES, ...user];
       return { ...user, beforeFiles: [...DECO_REWRITES, ...(user.beforeFiles ?? [])] };
     },
+    async headers() {
+      const user = typeof userHeaders === "function" ? await userHeaders() : (userHeaders ?? []);
+      // Draft rules first: a site's own catch-all Cache-Control must not win
+      // over the one thing standing between a draft and a shared cache.
+      return [...DECO_DRAFT_HEADERS, ...user];
+    },
   };
 }
 
-module.exports = { withDeco, DECO_REWRITES };
+module.exports = { withDeco, DECO_REWRITES, DECO_DRAFT_HEADERS };

package/src/config.test.ts

@@ -45,3 +45,42 @@ describe("withDeco", () => {
     expect(cfg.transpilePackages).toContain("other");
   });
 });
+
+describe("withDeco draft headers", () => {
+  it("adds no-store/no-index rules for both draft signals", async () => {
+    const headers = await withDeco({}).headers!();
+    // Two rules, not one: `has` entries within a rule are ANDed, and the query
+    // (entry) and cookie (navigation) signals never coincide.
+    expect(headers).toHaveLength(2);
+    expect(headers[0].has).toEqual([{ type: "query", key: "__draft" }]);
+    expect(headers[1].has).toEqual([{ type: "cookie", key: "__deco_draft" }]);
+
+    for (const rule of headers) {
+      const byKey = Object.fromEntries(rule.headers.map((h) => [h.key, h.value]));
+      // `no-store` is what actually stops a shared cache serving unpublished
+      // content to a real visitor — the pointer being a cookie means draft and
+      // published share a URL.
+      expect(byKey["Cache-Control"]).toBe("no-store, private");
+      expect(byKey.Vary).toBe("Cookie");
+      expect(byKey["X-Robots-Tag"]).toBe("noindex, nofollow");
+    }
+  });
+
+  it("keeps a site's own headers, with the draft rules taking precedence", async () => {
+    const cfg = withDeco({
+      headers: async () => [
+        { source: "/:path*", headers: [{ key: "Cache-Control", value: "public, max-age=3600" }] },
+      ],
+    });
+    const headers = await cfg.headers!();
+    expect(headers).toHaveLength(3);
+    // A site's catch-all cache policy must not out-rank the draft rules.
+    expect(headers[0].has).toBeDefined();
+    expect(headers[1].has).toBeDefined();
+    expect(headers[2].headers[0].value).toBe("public, max-age=3600");
+  });
+
+  it("leaves a site without headers() untouched apart from the draft rules", async () => {
+    expect(await withDeco({}).headers!()).toHaveLength(2);
+  });
+});