@backmatter/next 0.0.8 → 0.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backmatter/next",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "description": "Experimental Next.js adapter for Backmatter. APIs will break. Not ready for production.",
   "type": "module",
   "publishConfig": {
@@ -38,7 +38,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@backmatter/core": "^0.0.8",
+    "@backmatter/core": "^0.0.9",
     "@mdx-js/mdx": "^3.1.1",
     "remark-gfm": "^4.0.1"
   },

package/src/page-render.ts

@@ -1,5 +1,5 @@
 // packages/next/src/page-render.ts
-import { Suspense, createElement, type ComponentType, type ReactNode } from "react";
+import { createElement, type ComponentType, type ReactNode } from "react";
 import { imageUrlFromUnknown, type BackmatterDoc } from "@backmatter/core";
 
 export type BlockModule = Record<string, unknown>;
@@ -50,17 +50,24 @@ export function asBlockLoader(type: string, value: ComponentType<any> | BlockLoa
 
 const resolvedBlocks = new WeakMap<BlockLoader, Promise<ComponentType<any> | undefined>>();
 
+async function loadBlockComponent(
+  type: string,
+  loader: BlockLoader,
+): Promise<ComponentType<any> | undefined> {
+  let pending = resolvedBlocks.get(loader);
+  if (!pending) {
+    pending = loader().then((mod) => resolveBlockComponent(mod, type));
+    resolvedBlocks.set(loader, pending);
+  }
+  return pending;
+}
+
 export async function LazyBlock(props: {
   type: string;
   loader: BlockLoader;
   blockProps: Record<string, unknown>;
 }) {
-  let pending = resolvedBlocks.get(props.loader);
-  if (!pending) {
-    pending = props.loader().then((mod) => resolveBlockComponent(mod, props.type));
-    resolvedBlocks.set(props.loader, pending);
-  }
-  const Cmp = await pending;
+  const Cmp = await loadBlockComponent(props.type, props.loader);
   if (!Cmp) {
     console.warn(`[backmatter] skipping unknown block type "${props.type}"`);
     return null;
@@ -69,43 +76,37 @@ export async function LazyBlock(props: {
 }
 
 /** Render a page document's `blocks` array. Unknown types are skipped. */
-export function renderPage(
+export async function renderPage(
   doc: Pick<BackmatterDoc, "frontmatter">,
   components?: BlockComponents,
-  fallbacks?: BlockFallbacks,
-): ReactNode {
+  _fallbacks?: BlockFallbacks,
+): Promise<ReactNode> {
   const blocks = asBlocks(doc.frontmatter.blocks);
-  const children: ReactNode[] = [];
-  for (const block of blocks) {
-    if (typeof block.type !== "string") continue;
-    const entry = components?.[block.type];
-    if (!entry) {
-      console.warn(`[backmatter] skipping unknown block type "${block.type}"`);
-      continue;
-    }
-    const raw =
-      block.props && typeof block.props === "object" && !Array.isArray(block.props)
-        ? (block.props as Record<string, unknown>)
-        : {};
-    const props: Record<string, unknown> = {};
-    for (const [name, value] of Object.entries(raw)) {
-      props[name] = imageUrlFromUnknown(value);
-    }
-    const key = typeof block.id === "string" ? block.id : undefined;
-    children.push(
-      createElement(
-        Suspense,
-        {
-          key,
-          fallback: createElement(fallbacks?.[block.type] ?? BlockSkeleton),
-        },
-        createElement(LazyBlock, {
-          type: block.type,
-          loader: asBlockLoader(block.type, entry),
-          blockProps: props,
-        }),
-      ),
-    );
-  }
-  return children.length === 0 ? null : children;
+  const children = await Promise.all(
+    blocks.map(async (block) => {
+      if (typeof block.type !== "string") return null;
+      const entry = components?.[block.type];
+      if (!entry) {
+        console.warn(`[backmatter] skipping unknown block type "${block.type}"`);
+        return null;
+      }
+      const raw =
+        block.props && typeof block.props === "object" && !Array.isArray(block.props)
+          ? (block.props as Record<string, unknown>)
+          : {};
+      const props: Record<string, unknown> = {};
+      for (const [name, value] of Object.entries(raw)) {
+        props[name] = imageUrlFromUnknown(value);
+      }
+      const Cmp = await loadBlockComponent(block.type, asBlockLoader(block.type, entry));
+      if (!Cmp) {
+        console.warn(`[backmatter] skipping unknown block type "${block.type}"`);
+        return null;
+      }
+      const key = typeof block.id === "string" ? block.id : undefined;
+      return createElement(Cmp, { key, ...props });
+    }),
+  );
+  const rendered = children.filter((child) => child != null);
+  return rendered.length === 0 ? null : rendered;
 }

package/src/revalidate.ts

@@ -12,7 +12,7 @@ import type { BackmatterClient } from "@backmatter/core/node/create-backmatter";
 
 export type RevalidateCache = {
   revalidatePath: (path: string, type?: "layout" | "page") => void;
-  revalidateTag: (tag: string) => void;
+  revalidateTag: (tag: string, profile?: string | { expire?: number }) => void;
 };
 
 function extractBearer(header: string | null): string | null {
@@ -57,7 +57,7 @@ export function createRevalidateRoute(
     const { revalidatePath, revalidateTag } = cache ?? (await loadNextCache());
     const paths = pathsForCommittedDocs(cms.models, body.docs ?? []);
     for (const path of paths) revalidatePath(path);
-    revalidateTag(BACKMATTER_CACHE_TAG);
+    revalidateTag(BACKMATTER_CACHE_TAG, { expire: 0 });
     if (body.full) revalidatePath("/", "layout");
     return Response.json({ ok: true, paths });
   };

package/src/routes.ts

@@ -3,15 +3,13 @@
 // app/[[...backmatter]]/page.tsx. It maps the URL to a document via each model's
 // `route` template (including `/` via indexSlug), loads it and renders MDX
 // or JSON pages. An optional catch-all is required so `/` is a CMS route.
-import { Suspense, createElement, type ReactNode } from "react";
+import { Fragment, Suspense, createElement, type ReactNode } from "react";
 import { matchRoute, modelFormat, PREVIEW_CHECKOUT_QUERY, PREVIEW_COOKIE, readPreviewCookie, routeSegments, type BackmatterDoc, type ModelDef } from "@backmatter/core";
 import type { BackmatterClient } from "@backmatter/core/node/create-backmatter";
 import { fetchPreviewDoc } from "@backmatter/core/preview";
 import { renderDoc, type MdxComponents } from "./mdx-compile";
 import { getCachedDoc, registerCachedDocGet } from "./cached-doc";
-import { BlockSkeleton, renderPage, type BlockComponents, type BlockFallbacks } from "./page-render";
-import { PreviewBody } from "./preview-live";
-import { PreviewPageReloader } from "./preview-refresh";
+import { renderPage, type BlockComponents, type BlockFallbacks } from "./page-render";
 import { previewUnavailable } from "./preview-ui";
 
 export const CATCH_ALL_PARAM = "backmatter";
@@ -25,7 +23,7 @@ export type CatchAllOptions = {
   components?: MdxComponents;
   /** Composer map, usually the generated `blocks`. */
   blocks?: BlockComponents;
-  /** Per-block Suspense fallbacks for page-format documents. */
+  /** Kept for host compatibility. Published pages resolve blocks before paint. */
   fallbacks?: BlockFallbacks;
   /** Per-type wrappers, usually the generated `layouts`. */
   layouts?: Record<string, DocLayout>;
@@ -89,6 +87,8 @@ type PreviewState =
   | { enabled: false }
   | { enabled: true; checkout: { branch?: string; tree?: string }; error?: string };
 
+type RouteHit = { locale: string; type: string; slug: string };
+
 async function checkoutQueryToken(
   searchParams: Promise<CatchAllSearchParams> | CatchAllSearchParams | undefined,
 ): Promise<string | undefined> {
@@ -157,81 +157,128 @@ export function createCatchAll<Models extends readonly ModelDef[]>(
     return params;
   };
 
-  const PageFallback = BlockSkeleton;
+  const failFor = options.notFound ?? nextNotFound;
 
-  const CmsRoute: CatchAllRoute["CmsRoute"] = async ({ params, searchParams }) => {
-    const resolved = await params;
-    const hit = resolve(resolved[CATCH_ALL_PARAM]);
-    const fail = options.notFound ?? nextNotFound;
-    if (!hit) return fail();
-    const preview = await resolvePreviewState(cms, options.preview, searchParams);
-    let doc: BackmatterDoc | null;
-    if (preview.enabled) {
-      if (preview.error) return previewUnavailable(preview.error);
-      try {
-        const getDoc =
-          options.preview?.getDoc ??
-          ((ref) =>
-            fetchPreviewDoc(
-              {
-                apiUrl: cms.config.apiUrl ?? "",
-                workspaceId: cms.config.workspaceId ?? "",
-                previewToken: cms.config.previewToken ?? "",
-              },
-              ref,
-            ));
-        doc = await getDoc({
-          locale: hit.locale,
-          type: hit.type,
-          slug: hit.slug,
-          ...preview.checkout,
-        });
-      } catch (err) {
-        return previewUnavailable(err instanceof Error ? err.message : "Failed to load");
-      }
-    } else {
-      doc = await getCachedDoc(hit.locale, hit.type, hit.slug);
-    }
-    if (!doc) return fail();
-    const model = byType.get(hit.type);
+  async function layoutDoc(doc: BackmatterDoc, previewEnabled: boolean): Promise<ReactNode> {
+    const model = byType.get(doc.type);
     const isPage = Boolean(model && modelFormat(model) === "page");
     const rendered = isPage
-      ? renderPage(doc, options.blocks, options.fallbacks)
+      ? await renderPage(doc, options.blocks, options.fallbacks)
       : await renderDoc(doc, { components: options.components });
-    const body = isPage
-      ? rendered
-      : preview.enabled
-        ? createElement(
-            PreviewBody,
-            { doc, components: options.components },
-            rendered,
-          )
-        : rendered;
-    const withLive =
-      preview.enabled && isPage
-        ? createElement(
-            "div",
-            null,
-            createElement(PreviewPageReloader, {
-              locale: doc.locale,
-              type: doc.type,
-              slug: doc.slug,
-            }),
-            body,
-          )
-        : body;
-    const layout = options.layouts?.[hit.type];
-    const laidOut = layout ? layout(doc, withLive) : withLive;
+    let body = rendered;
+    if (!isPage && previewEnabled) {
+      const { PreviewBody } = await import("./preview-live");
+      body = createElement(PreviewBody, { doc, components: options.components }, rendered);
+    }
+    if (previewEnabled && isPage) {
+      const { PreviewPageReloader } = await import("./preview-refresh");
+      body = createElement(
+        "div",
+        null,
+        createElement(PreviewPageReloader, {
+          locale: doc.locale,
+          type: doc.type,
+          slug: doc.slug,
+        }),
+        body,
+      );
+    }
+    const layout = options.layouts?.[doc.type];
+    const laidOut = layout ? layout(doc, body) : body;
     if (options.render) return options.render(doc, laidOut);
     if (layout || isPage) return laidOut;
     return createElement("article", null, laidOut);
+  }
+
+  async function loadPreviewDoc(
+    hit: RouteHit,
+    preview: Extract<PreviewState, { enabled: true }>,
+  ): Promise<ReactNode> {
+    if (preview.error) return previewUnavailable(preview.error);
+    try {
+      const getDoc =
+        options.preview?.getDoc ??
+        ((ref) =>
+          fetchPreviewDoc(
+            {
+              apiUrl: cms.config.apiUrl ?? "",
+              workspaceId: cms.config.workspaceId ?? "",
+              previewToken: cms.config.previewToken ?? "",
+            },
+            ref,
+          ));
+      const doc = await getDoc({
+        locale: hit.locale,
+        type: hit.type,
+        slug: hit.slug,
+        ...preview.checkout,
+      });
+      if (!doc) return previewUnavailable("Document not found");
+      return layoutDoc(doc, true);
+    } catch (err) {
+      return previewUnavailable(err instanceof Error ? err.message : "Failed to load");
+    }
+  }
+
+  const CmsRoute: CatchAllRoute["CmsRoute"] = async ({ params, searchParams }) => {
+    const resolved = await params;
+    const hit = resolve(resolved[CATCH_ALL_PARAM]);
+    if (!hit) return failFor();
+    const preview = await resolvePreviewState(cms, options.preview, searchParams);
+    if (preview.enabled) return loadPreviewDoc(hit, preview);
+    const doc = await getCachedDoc(hit.locale, hit.type, hit.slug);
+    if (!doc) return failFor();
+    return layoutDoc(doc, false);
+  };
+
+  const PublishedRoute = async ({
+    params,
+  }: {
+    params: Promise<CatchAllParams> | CatchAllParams;
+    searchParams?: Promise<CatchAllSearchParams> | CatchAllSearchParams;
+  }) => {
+    const resolved = await params;
+    const hit = resolve(resolved[CATCH_ALL_PARAM]);
+    if (!hit) return failFor();
+    const doc = await getCachedDoc(hit.locale, hit.type, hit.slug);
+    if (!doc) return failFor();
+    return createElement(
+      "div",
+      { "data-backmatter-published": "", style: { display: "contents" } },
+      await layoutDoc(doc, false),
+    );
+  };
+
+  const PreviewBranch = async ({
+    params,
+    searchParams,
+  }: {
+    params: Promise<CatchAllParams> | CatchAllParams;
+    searchParams?: Promise<CatchAllSearchParams> | CatchAllSearchParams;
+  }) => {
+    const resolved = await params;
+    const hit = resolve(resolved[CATCH_ALL_PARAM]);
+    if (!hit) return null;
+    const preview = await resolvePreviewState(cms, options.preview, searchParams);
+    if (!preview.enabled) return null;
+    return createElement(
+      Fragment,
+      null,
+      createElement("style", {
+        dangerouslySetInnerHTML: {
+          __html: "[data-backmatter-published]{display:none!important}",
+        },
+      }),
+      await loadPreviewDoc(hit, preview),
+    );
   };
 
   const Page: CatchAllRoute["Page"] = (props) =>
     createElement(
-      Suspense,
-      { fallback: createElement(PageFallback) },
-      createElement(CmsRoute, props),
+      Fragment,
+      null,
+      createElement(PublishedRoute, props),
+      createElement(Suspense, { fallback: null }, createElement(PreviewBranch, props)),
     );
 
   const generateMetadata: CatchAllRoute["generateMetadata"] = async ({ params }) => {