@backmatter/next 0.0.10 → 0.0.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backmatter/next",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "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.11",
     "@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/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";
 
@@ -62,7 +62,7 @@ export type CatchAllRoute = {
   Page: (props: {
     params: Promise<CatchAllParams>;
     searchParams?: Promise<CatchAllSearchParams>;
-  }) => ReactNode;
+  }) => Promise<ReactNode>;
   CmsRoute: (props: {
     params: Promise<CatchAllParams> | CatchAllParams;
     searchParams?: Promise<CatchAllSearchParams> | CatchAllSearchParams;
@@ -133,7 +133,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 +220,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);
+    const doc = await cms.getDoc(hit.locale, hit.type, hit.slug);
     if (!doc) return failFor();
     return layoutDoc(doc, false);
   };
@@ -237,10 +236,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,7 +255,7 @@ 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);
@@ -273,19 +272,19 @@ export function createCatchAll<Models extends readonly ModelDef[]>(
     );
   };
 
-  const Page: CatchAllRoute["Page"] = (props) =>
+  const Page: CatchAllRoute["Page"] = async (props) =>
     createElement(
       Fragment,
       null,
-      createElement(PublishedRoute, props),
+      await PublishedRoute(props),
       createElement(Suspense, { fallback: null }, createElement(PreviewBranch, props)),
     );
 
   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 };