@backmatter/next 0.0.11 → 0.0.13

package/dist/config.cjs

@@ -180,8 +180,40 @@ function detectSdk(root) {
   } catch {}
   return "@backmatter/core/node";
 }
+function renderCachedCmsClient() {
+  return [
+    "const raw = createBackmatter({ ...config, models });",
+    "",
+    "async function getDoc(locale: string, type: string, slug: string) {",
+    '  "use cache";',
+    '  cacheLife("hours");',
+    "  cacheTag(...contentCacheTags(locale, type, slug));",
+    "  return raw.getDoc(locale, type, slug);",
+    "}",
+    "",
+    "async function listDocs(filter?: { type?: string; locale?: string }) {",
+    '  "use cache";',
+    '  cacheLife("hours");',
+    "  cacheTag(...listCacheTags(filter?.type));",
+    "  return raw.listDocs(filter);",
+    "}",
+    "",
+    "/** Typed content client: cms.query.{type}, cms.getDoc, cms.listDocs. */",
+    "export const cms = {",
+    "  ...raw,",
+    "  getDoc,",
+    "  listDocs,",
+    `  query: createQuery(models, { getDoc, listDocs }),`,
+    "};"
+  ];
+}
 function renderModelsBarrel(input) {
+  const nextHost = input.sdk === "@backmatter/next";
   const lines = [GENERATED_HEADER, `import { createBackmatter } from "${input.sdk}";`];
+  if (nextHost) {
+    lines.push('import { contentCacheTags, createQuery, listCacheTags } from "@backmatter/core";');
+    lines.push('import { cacheLife, cacheTag } from "next/cache";');
+  }
   if (input.configFile) {
     lines.push(`import config from "${importSpecifier(input.outDir, input.configFile)}";`);
   } else {
@@ -194,8 +226,12 @@ function renderModelsBarrel(input) {
   lines.push(`export const models = [${input.models.map((m) => m.importName).join(", ")}] as const;`);
   lines.push("export type Models = typeof models;");
   lines.push("");
-  lines.push("/** Typed content client: cms.query.{type}, cms.getDoc, cms.listDocs. */");
-  lines.push("export const cms = createBackmatter({ ...config, models });");
+  if (nextHost) {
+    lines.push(...renderCachedCmsClient());
+  } else {
+    lines.push("/** Typed content client: cms.query.{type}, cms.getDoc, cms.listDocs. */");
+    lines.push("export const cms = createBackmatter({ ...config, models });");
+  }
   return `${lines.join(`
 `)}
 `;
@@ -395,10 +431,14 @@ function withBackmatter(nextConfig = {}, options = {}) {
     return cfg.webpack ? cfg.webpack(config, context) : config;
   };
   const cacheComponents = cfg.cacheComponents ?? true;
+  const transpilePackages = [
+    ...new Set([...cfg.transpilePackages ?? [], "@backmatter/next", "@backmatter/core"])
+  ];
   return {
     ...nextConfig,
     cacheComponents,
     partialPrefetching: cfg.partialPrefetching ?? cacheComponents,
+    transpilePackages,
     turbopack,
     webpack
   };

package/dist/loader.cjs

@@ -174,8 +174,40 @@ function detectSdk(root) {
   } catch {}
   return "@backmatter/core/node";
 }
+function renderCachedCmsClient() {
+  return [
+    "const raw = createBackmatter({ ...config, models });",
+    "",
+    "async function getDoc(locale: string, type: string, slug: string) {",
+    '  "use cache";',
+    '  cacheLife("hours");',
+    "  cacheTag(...contentCacheTags(locale, type, slug));",
+    "  return raw.getDoc(locale, type, slug);",
+    "}",
+    "",
+    "async function listDocs(filter?: { type?: string; locale?: string }) {",
+    '  "use cache";',
+    '  cacheLife("hours");',
+    "  cacheTag(...listCacheTags(filter?.type));",
+    "  return raw.listDocs(filter);",
+    "}",
+    "",
+    "/** Typed content client: cms.query.{type}, cms.getDoc, cms.listDocs. */",
+    "export const cms = {",
+    "  ...raw,",
+    "  getDoc,",
+    "  listDocs,",
+    `  query: createQuery(models, { getDoc, listDocs }),`,
+    "};"
+  ];
+}
 function renderModelsBarrel(input) {
+  const nextHost = input.sdk === "@backmatter/next";
   const lines = [GENERATED_HEADER, `import { createBackmatter } from "${input.sdk}";`];
+  if (nextHost) {
+    lines.push('import { contentCacheTags, createQuery, listCacheTags } from "@backmatter/core";');
+    lines.push('import { cacheLife, cacheTag } from "next/cache";');
+  }
   if (input.configFile) {
     lines.push(`import config from "${importSpecifier(input.outDir, input.configFile)}";`);
   } else {
@@ -188,8 +220,12 @@ function renderModelsBarrel(input) {
   lines.push(`export const models = [${input.models.map((m) => m.importName).join(", ")}] as const;`);
   lines.push("export type Models = typeof models;");
   lines.push("");
-  lines.push("/** Typed content client: cms.query.{type}, cms.getDoc, cms.listDocs. */");
-  lines.push("export const cms = createBackmatter({ ...config, models });");
+  if (nextHost) {
+    lines.push(...renderCachedCmsClient());
+  } else {
+    lines.push("/** Typed content client: cms.query.{type}, cms.getDoc, cms.listDocs. */");
+    lines.push("export const cms = createBackmatter({ ...config, models });");
+  }
   return `${lines.join(`
 `)}
 `;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backmatter/next",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "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.10",
+    "@backmatter/core": "^0.0.12",
     "@mdx-js/mdx": "^3.1.1",
     "remark-gfm": "^4.0.1"
   },

package/src/cached-doc.ts

@@ -1,5 +1,5 @@
 // packages/next/src/cached-doc.ts
-import { contentCacheTags, type BackmatterDoc } from "@backmatter/core";
+import { contentCacheTags, listCacheTags, type BackmatterDoc, type BackmatterDocSummary } from "@backmatter/core";
 
 export type CacheFns = {
   cacheLife: (profile: string) => void;
@@ -12,13 +12,23 @@ export type GetDocFn = (
   slug: string,
 ) => Promise<BackmatterDoc | null>;
 
+export type ListDocsFn = (filter?: {
+  type?: string;
+  locale?: string;
+}) => Promise<BackmatterDocSummary[]>;
+
 let registeredGetDoc: GetDocFn | null = null;
+let registeredListDocs: ListDocsFn | null = null;
 
-/** Called from `createCatchAll` so `"use cache"` only closes over serializable args. */
+/** Called from `createBackmatter` so `"use cache"` only closes over serializable args. */
 export function registerCachedDocGet(getDoc: GetDocFn): void {
   registeredGetDoc = getDoc;
 }
 
+export function registerCachedListDocs(listDocs: ListDocsFn): void {
+  registeredListDocs = listDocs;
+}
+
 async function loadCacheFns(): Promise<CacheFns> {
   try {
     const mod = (await import("next/cache" as string)) as CacheFns;
@@ -49,7 +59,34 @@ export async function getCachedDoc(
   fns.cacheTag(...contentCacheTags(locale, type, slug));
   const getDoc = registeredGetDoc;
   if (!getDoc) {
-    throw new Error("[backmatter] getCachedDoc called before createCatchAll registered getDoc");
+    throw new Error("[backmatter] getCachedDoc called before createBackmatter registered getDoc");
   }
   return getDoc(locale, type, slug);
 }
+
+export async function getCachedDocs(
+  type?: string,
+  locale?: string,
+  cache?: CacheFns,
+): Promise<BackmatterDocSummary[]> {
+  "use cache";
+  const fns = cache ?? (await loadCacheFns());
+  fns.cacheLife("hours");
+  fns.cacheTag(...listCacheTags(type));
+  const listDocs = registeredListDocs;
+  if (!listDocs) {
+    throw new Error("[backmatter] getCachedDocs called before createBackmatter registered listDocs");
+  }
+  return listDocs({ type, locale });
+}
+
+/** Unwrap Next `params` inside `"use cache"` so Cache Components can prerender. */
+export async function cachedRouteParams<T extends object>(
+  params: Promise<T> | T,
+  cache?: CacheFns,
+): Promise<T> {
+  "use cache";
+  const fns = cache ?? (await loadCacheFns());
+  fns.cacheLife("hours");
+  return await params;
+}

package/src/config.ts

@@ -43,6 +43,7 @@ type TurbopackRule = { loaders: Array<{ loader: string; options: Record<string,
 export type NextConfigLike = {
   cacheComponents?: boolean;
   partialPrefetching?: boolean | "unstable_eager";
+  transpilePackages?: string[];
   turbopack?: Record<string, unknown>;
   webpack?: ((config: WebpackConfigLike, context: any) => WebpackConfigLike) | null;
 } & Record<string, unknown>;
@@ -119,6 +120,7 @@ export function registryMatchers(loaderOptions: BackmatterLoaderOptions): { glob
 export type WithBackmatterResult<T extends object> = Omit<T, "turbopack" | "webpack"> & {
   cacheComponents: boolean;
   partialPrefetching: boolean | "unstable_eager";
+  transpilePackages: string[];
   turbopack: Record<string, unknown>;
   webpack: NonNullable<NextConfigLike["webpack"]>;
 };
@@ -150,10 +152,14 @@ export function withBackmatter<T extends object>(
   };
 
   const cacheComponents = cfg.cacheComponents ?? true;
+  const transpilePackages = [
+    ...new Set([...(cfg.transpilePackages ?? []), "@backmatter/next", "@backmatter/core"]),
+  ];
   return {
     ...nextConfig,
     cacheComponents,
     partialPrefetching: cfg.partialPrefetching ?? cacheComponents,
+    transpilePackages,
     turbopack,
     webpack,
   };

package/src/create-backmatter.ts

@@ -1,15 +1,29 @@
 // packages/next/src/create-backmatter.ts
 // Next hosts cache API fetches with tags so `content.committed` can
 // `revalidateTag("backmatter")`. Core/CLI keep `cache: "no-store"`.
+// getDoc/listDocs also go through `"use cache"` so Cache Components can prerender.
+import { createQuery, type ModelDef } from "@backmatter/core";
 import {
   createBackmatter as createCore,
   type CreateBackmatterOptions,
   type BackmatterClient,
 } from "@backmatter/core/node/create-backmatter";
-import type { ModelDef } from "@backmatter/core";
+import { getCachedDoc, getCachedDocs, registerCachedDocGet, registerCachedListDocs } from "./cached-doc";
 
 export function createBackmatter<const Models extends readonly ModelDef[]>(
   options: CreateBackmatterOptions<Models>,
 ): BackmatterClient<Models> {
-  return createCore({ ...options, taggedApiFetch: true });
+  const core = createCore({ ...options, taggedApiFetch: true });
+  registerCachedDocGet(core.getDoc);
+  registerCachedListDocs(core.listDocs);
+  const getDoc: BackmatterClient<Models>["getDoc"] = (locale, type, slug) =>
+    getCachedDoc(locale, type, slug);
+  const listDocs: BackmatterClient<Models>["listDocs"] = (filter) =>
+    getCachedDocs(filter?.type, filter?.locale);
+  return {
+    ...core,
+    getDoc,
+    listDocs,
+    query: createQuery(options.models, { getDoc, listDocs }),
+  };
 }

package/src/devbar-client.tsx

@@ -16,7 +16,7 @@ export type DevModeState =
   | { status: "hidden" }
   | {
       status: "ready";
-      user: CmsSessionUser;
+      user?: CmsSessionUser;
       mode: "preview" | "live";
       branch?: string;
       tree?: string;
@@ -26,28 +26,37 @@ export function devModeState(
   user: CmsSessionUser | null,
   session: { enabled: boolean; branch?: string; tree?: string },
 ): DevModeState {
-  if (!user) return { status: "hidden" };
+  if (!user && !session.enabled) return { status: "hidden" };
   const resolved = resolveDevMode(session);
   return {
     status: "ready",
-    user,
+    ...(user ? { user } : {}),
     ...resolved,
   };
 }
 
+export async function loadDevModeState(
+  apiUrl: string,
+  fetchUser: typeof fetchCmsSession = fetchCmsSession,
+  fetchSession: typeof fetchHostPreviewSession = fetchHostPreviewSession,
+): Promise<DevModeState> {
+  const trimmed = apiUrl.trim();
+  const [user, session] = await Promise.all([
+    trimmed ? fetchUser(trimmed) : Promise.resolve(null),
+    fetchSession(""),
+  ]);
+  return devModeState(user, session);
+}
+
 export function useDevMode(options: { apiUrl: string }): DevModeState {
   const [state, setState] = useState<DevModeState>({ status: "hidden" });
 
   useEffect(() => {
-    const apiUrl = options.apiUrl.trim();
-    if (!apiUrl) return;
     let cancelled = false;
-    void Promise.all([fetchCmsSession(apiUrl), fetchHostPreviewSession("")]).then(
-      ([user, session]) => {
-        if (cancelled) return;
-        setState(devModeState(user, session));
-      },
-    );
+    void loadDevModeState(options.apiUrl).then((next) => {
+      if (cancelled) return;
+      setState(next);
+    });
     return () => {
       cancelled = true;
     };

package/src/devbar.tsx

@@ -7,6 +7,7 @@ export {
   DevBarView,
   devModeState,
   exitHostPreview,
+  loadDevModeState,
   useDevMode,
   type CmsSessionUser,
   type DevModeState,

package/src/preview-route.ts

@@ -15,6 +15,7 @@ import type { BackmatterClient } from "@backmatter/core/node/create-backmatter";
 export type PreviewRouteDeps = {
   enableDraft?: () => void | Promise<void>;
   disableDraft?: () => void | Promise<void>;
+  isDraftEnabled?: () => boolean | Promise<boolean>;
   now?: () => number;
 };
 
@@ -45,6 +46,13 @@ async function nextDraft(enable: boolean): Promise<void> {
   else draft.disable();
 }
 
+async function nextDraftEnabled(): Promise<boolean> {
+  const mod = (await import("next/headers" as string)) as {
+    draftMode: () => Promise<{ isEnabled: boolean }>;
+  };
+  return (await mod.draftMode()).isEnabled;
+}
+
 function cookieFrom(req: Request): string | undefined {
   const header = req.headers.get("cookie");
   if (!header) return undefined;
@@ -75,11 +83,14 @@ export function createPreviewRoute(
 
     if (url.searchParams.get("session") === "1") {
       const checkout = secret ? await checkoutFrom(req, secret, url) : null;
-      if (!checkout) return Response.json({ mode: "live" });
-      return Response.json({
-        mode: "preview",
-        ...checkout,
-      });
+      if (checkout) {
+        return Response.json({
+          mode: "preview",
+          ...checkout,
+        });
+      }
+      const draftOn = await (deps.isDraftEnabled ?? nextDraftEnabled)();
+      return Response.json({ mode: draftOn ? "preview" : "live" });
     }
 
     if (url.searchParams.get("stream") === "1") {

package/src/routes.ts

@@ -8,7 +8,7 @@ import { matchRoute, modelFormat, PREVIEW_CHECKOUT_QUERY, PREVIEW_COOKIE, readPr
 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 { cachedRouteParams } from "./cached-doc";
 import { renderPage, type BlockComponents, type BlockFallbacks } from "./page-render";
 import { previewUnavailable } from "./preview-ui";
 
@@ -44,6 +44,7 @@ export type CatchAllOptions = {
   preview?: {
     enabled: boolean;
     checkout?: { branch?: string; tree?: string };
+    error?: string;
     getDoc?: (ref: {
       locale: string;
       type: string;
@@ -87,6 +88,13 @@ type PreviewState =
   | { enabled: false }
   | { enabled: true; checkout: { branch?: string; tree?: string }; error?: string };
 
+/** Draft without a readable checkout stays on the published page. */
+export function previewReplacesPublished(
+  preview: PreviewState,
+): preview is Extract<PreviewState, { enabled: true }> {
+  return preview.enabled && preview.error !== "invalid_session";
+}
+
 type RouteHit = { locale: string; type: string; slug: string };
 
 async function checkoutQueryToken(
@@ -107,7 +115,11 @@ async function resolvePreviewState(
 ): Promise<PreviewState> {
   if (injected) {
     if (!injected.enabled) return { enabled: false };
-    return { enabled: true, checkout: injected.checkout ?? {} };
+    return {
+      enabled: true,
+      checkout: injected.checkout ?? {},
+      ...(injected.error ? { error: injected.error } : {}),
+    };
   }
   try {
     const mod = (await import("next/headers" as string)) as {
@@ -133,7 +145,6 @@ export function createCatchAll<Models extends readonly ModelDef[]>(
   cms: BackmatterClient<Models>,
   options: CatchAllOptions = {},
 ): CatchAllRoute {
-  registerCachedDocGet((locale, type, slug) => cms.getDoc(locale, type, slug));
   const models = cms.models as readonly ModelDef[];
   const byType = new Map(models.map((m) => [m.type, m]));
   const matchOptions = {
@@ -221,12 +232,12 @@ export function createCatchAll<Models extends readonly ModelDef[]>(
   }
 
   const CmsRoute: CatchAllRoute["CmsRoute"] = async ({ params, searchParams }) => {
-    const resolved = await params;
+    const resolved = await cachedRouteParams(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 (previewReplacesPublished(preview)) return loadPreviewDoc(hit, preview);
+    const doc = await cms.getDoc(hit.locale, hit.type, hit.slug);
     if (!doc) return failFor();
     return layoutDoc(doc, false);
   };
@@ -237,10 +248,10 @@ export function createCatchAll<Models extends readonly ModelDef[]>(
     params: Promise<CatchAllParams> | CatchAllParams;
     searchParams?: Promise<CatchAllSearchParams> | CatchAllSearchParams;
   }) => {
-    const resolved = await params;
+    const resolved = await cachedRouteParams(params);
     const hit = resolve(resolved[CATCH_ALL_PARAM]);
     if (!hit) return failFor();
-    const doc = await getCachedDoc(hit.locale, hit.type, hit.slug);
+    const doc = await cms.getDoc(hit.locale, hit.type, hit.slug);
     if (!doc) return failFor();
     return createElement(
       "div",
@@ -256,11 +267,11 @@ export function createCatchAll<Models extends readonly ModelDef[]>(
     params: Promise<CatchAllParams> | CatchAllParams;
     searchParams?: Promise<CatchAllSearchParams> | CatchAllSearchParams;
   }) => {
-    const resolved = await params;
+    const resolved = await cachedRouteParams(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;
+    if (!previewReplacesPublished(preview)) return null;
     return createElement(
       Fragment,
       null,
@@ -282,10 +293,10 @@ export function createCatchAll<Models extends readonly ModelDef[]>(
     );
 
   const generateMetadata: CatchAllRoute["generateMetadata"] = async ({ params }) => {
-    const resolved = await params;
+    const resolved = await cachedRouteParams(params);
     const hit = resolve(resolved[CATCH_ALL_PARAM]);
     if (!hit) return {};
-    const doc = await getCachedDoc(hit.locale, hit.type, hit.slug);
+    const doc = await cms.getDoc(hit.locale, hit.type, hit.slug);
     if (!doc) return {};
     const title = doc.frontmatter.title;
     return { title: typeof title === "string" ? title : hit.slug };