@backmatter/next 0.0.18 → 0.0.19

package/dist/config.cjs

@@ -73,8 +73,8 @@ __export(exports_config, {
   withBackmatter: () => withBackmatter
 });
 module.exports = __toCommonJS(exports_config);
-var import_node_fs3 = require("node:fs");
-var import_node_path3 = __toESM(require("node:path"));
+var import_node_fs4 = require("node:fs");
+var import_node_path4 = __toESM(require("node:path"));
 
 // ../core/src/node/generate.ts
 var import_node_fs2 = require("node:fs");
@@ -398,16 +398,295 @@ function generate(options) {
   };
 }
 
+// ../core/src/node/registry-import.ts
+var import_node_fs3 = require("node:fs");
+var import_node_path3 = __toESM(require("node:path"));
+var REGISTRY_SPECIFIER = "backmatter";
+function registryAliases() {
+  return REGISTRY_FILES.map((file) => {
+    const stem = file.slice(0, -".ts".length);
+    return {
+      specifier: stem === "index" ? REGISTRY_SPECIFIER : `${REGISTRY_SPECIFIER}/${stem}`,
+      file
+    };
+  });
+}
+function registryTurbopackAlias(appRoot, outDir = DEFAULT_OUT_DIR) {
+  const alias = {};
+  const base = import_node_path3.default.resolve(appRoot);
+  for (const { specifier, file } of registryAliases()) {
+    const abs = import_node_path3.default.resolve(appRoot, outDir, file);
+    alias[specifier] = asRelative(import_node_path3.default.relative(base, abs).split(import_node_path3.default.sep).join("/"));
+  }
+  return alias;
+}
+function registryWebpackAlias(root, outDir = DEFAULT_OUT_DIR) {
+  const alias = {};
+  for (const { specifier, file } of registryAliases()) {
+    alias[`${specifier}$`] = import_node_path3.default.resolve(root, outDir, file);
+  }
+  return alias;
+}
+function registryImportPaths(outDir = DEFAULT_OUT_DIR, baseUrl) {
+  const base = !baseUrl || baseUrl === "." ? "." : baseUrl;
+  const from = import_node_path3.default.resolve("/registry-root", base);
+  const to = import_node_path3.default.resolve("/registry-root", outDir);
+  const folder = asRelative(import_node_path3.default.relative(from, to).split(import_node_path3.default.sep).join("/"));
+  const paths = {};
+  for (const { specifier, file } of registryAliases()) {
+    paths[specifier] = [`${folder}/${file}`];
+  }
+  return paths;
+}
+function addRegistryPaths(source, outDir = DEFAULT_OUT_DIR) {
+  let parsed;
+  try {
+    parsed = looseParse(source);
+  } catch {
+    return source;
+  }
+  if (!isRecord(parsed))
+    return source;
+  const options = parsed.compilerOptions;
+  if (!isRecord(options))
+    return source;
+  const baseUrl = typeof options.baseUrl === "string" ? options.baseUrl : undefined;
+  const mappings = registryImportPaths(outDir, baseUrl);
+  const existing = isRecord(options.paths) ? options.paths : undefined;
+  if (options.paths !== undefined && !existing)
+    return source;
+  const missing = Object.fromEntries(Object.entries(mappings).filter(([key]) => !existing || existing[key] === undefined));
+  if (Object.keys(missing).length === 0)
+    return source;
+  const compiler = findKeyBrace(source, "compilerOptions", 0, source.length);
+  if (!compiler)
+    return source;
+  const compilerEnd = matchBrace(source, compiler.brace);
+  if (compilerEnd < 0)
+    return source;
+  const nl = source.includes(`\r
+`) ? `\r
+` : `
+`;
+  if (existing) {
+    const pathsBrace = findKeyBrace(source, "paths", compiler.brace + 1, compilerEnd);
+    if (!pathsBrace || pathsBrace.brace > compilerEnd)
+      return source;
+    const indent2 = innerIndent(source, pathsBrace.brace);
+    const entries2 = formatEntries(missing, indent2, nl);
+    return insertEntries(source, pathsBrace.brace, entries2, indent2, nl);
+  }
+  const indent = innerIndent(source, compiler.brace);
+  const child = `${indent}  `;
+  const entries = formatEntries(missing, child, nl);
+  const block = `${indent}"paths": {${nl}${entries},${nl}${indent}}`;
+  return `${source.slice(0, compiler.brace + 1)}${nl}${block},${source.slice(compiler.brace + 1)}`;
+}
+function ensureRegistryTsconfig(root, outDir = DEFAULT_OUT_DIR) {
+  const tsconfig = import_node_path3.default.join(root, "tsconfig.json");
+  const jsconfig = import_node_path3.default.join(root, "jsconfig.json");
+  const file = import_node_fs3.existsSync(tsconfig) ? tsconfig : import_node_fs3.existsSync(jsconfig) ? jsconfig : null;
+  if (!file)
+    return null;
+  const before = import_node_fs3.readFileSync(file, "utf-8");
+  const after = addRegistryPaths(before, outDir);
+  if (after === before)
+    return null;
+  import_node_fs3.writeFileSync(file, after);
+  return `updated ${import_node_path3.default.basename(file)}`;
+}
+function asRelative(rel) {
+  if (rel.startsWith("./") || rel.startsWith("../"))
+    return rel;
+  return `./${rel}`;
+}
+function insertEntries(source, open, entries, indent, nl) {
+  let rest = source.slice(open + 1);
+  if (!/^\r?\n/.test(rest))
+    rest = `${nl}${indent}${rest.trimStart()}`;
+  return `${source.slice(0, open + 1)}${nl}${entries},${rest}`;
+}
+function formatEntries(mappings, indent, nl) {
+  return Object.entries(mappings).map(([key, value]) => `${indent}"${key}": [${value.map((entry) => JSON.stringify(entry)).join(", ")}]`).join(`,${nl}`);
+}
+function innerIndent(source, open) {
+  const rest = source.slice(open + 1);
+  const nl = rest.search(/\r?\n/);
+  if (nl !== -1) {
+    const after = rest.slice(nl).replace(/^\r?\n/, "");
+    const indent = after.match(/^[ \t]*/)?.[0] ?? "";
+    const next = after[indent.length];
+    if (indent.length > 0 && next && next !== "}")
+      return indent;
+  }
+  const lineStart = source.lastIndexOf(`
+`, open) + 1;
+  const base = source.slice(lineStart, open).match(/^[ \t]*/)?.[0] ?? "";
+  return `${base}  `;
+}
+function looseParse(source) {
+  const stripped = stripJsonComments(source).replace(/,\s*([}\]])/g, "$1");
+  return JSON.parse(stripped);
+}
+function stripJsonComments(input) {
+  let out = "";
+  let i = 0;
+  let inString = false;
+  let escaped = false;
+  while (i < input.length) {
+    const c = input[i];
+    const next = input[i + 1];
+    if (inString) {
+      out += c;
+      if (escaped)
+        escaped = false;
+      else if (c === "\\")
+        escaped = true;
+      else if (c === '"')
+        inString = false;
+      i++;
+      continue;
+    }
+    if (c === '"') {
+      inString = true;
+      out += c;
+      i++;
+      continue;
+    }
+    if (c === "/" && next === "/") {
+      i += 2;
+      while (i < input.length && input[i] !== `
+`)
+        i++;
+      continue;
+    }
+    if (c === "/" && next === "*") {
+      i += 2;
+      while (i < input.length && !(input[i] === "*" && input[i + 1] === "/"))
+        i++;
+      i += 2;
+      continue;
+    }
+    out += c;
+    i++;
+  }
+  return out;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function findKeyBrace(source, key, start, end) {
+  const needle = `"${key}"`;
+  let i = start;
+  let inString = false;
+  let escaped = false;
+  while (i < end) {
+    const c = source[i];
+    const next = source[i + 1];
+    if (inString) {
+      if (escaped)
+        escaped = false;
+      else if (c === "\\")
+        escaped = true;
+      else if (c === '"')
+        inString = false;
+      i++;
+      continue;
+    }
+    if (c === '"') {
+      if (source.startsWith(needle, i)) {
+        let j = i + needle.length;
+        while (j < end && /\s/.test(source[j]))
+          j++;
+        if (source[j] === ":") {
+          j++;
+          while (j < end && /\s/.test(source[j]))
+            j++;
+          if (source[j] === "{")
+            return { brace: j };
+        }
+      }
+      inString = true;
+      i++;
+      continue;
+    }
+    if (c === "/" && next === "/") {
+      i += 2;
+      while (i < end && source[i] !== `
+`)
+        i++;
+      continue;
+    }
+    if (c === "/" && next === "*") {
+      i += 2;
+      while (i < end && !(source[i] === "*" && source[i + 1] === "/"))
+        i++;
+      i += 2;
+      continue;
+    }
+    i++;
+  }
+  return null;
+}
+function matchBrace(source, open) {
+  let depth = 0;
+  let i = open;
+  let inString = false;
+  let escaped = false;
+  while (i < source.length) {
+    const c = source[i];
+    const next = source[i + 1];
+    if (inString) {
+      if (escaped)
+        escaped = false;
+      else if (c === "\\")
+        escaped = true;
+      else if (c === '"')
+        inString = false;
+      i++;
+      continue;
+    }
+    if (c === '"') {
+      inString = true;
+      i++;
+      continue;
+    }
+    if (c === "/" && next === "/") {
+      i += 2;
+      while (i < source.length && source[i] !== `
+`)
+        i++;
+      continue;
+    }
+    if (c === "/" && next === "*") {
+      i += 2;
+      while (i < source.length && !(source[i] === "*" && source[i + 1] === "/"))
+        i++;
+      i += 2;
+      continue;
+    }
+    if (c === "{")
+      depth++;
+    else if (c === "}") {
+      depth--;
+      if (depth === 0)
+        return i;
+    }
+    i++;
+  }
+  return -1;
+}
+
 // src/config.ts
 var LOADER = "@backmatter/next/loader";
 var SDK = "@backmatter/next";
 function warnMissingInstrumentation(root) {
   if (detectSdk(root) !== "@backmatter/next")
     return;
-  const hasRoot = import_node_fs3.existsSync(import_node_path3.default.join(root, "instrumentation.ts"));
-  const hasSrc = import_node_fs3.existsSync(import_node_path3.default.join(root, "src", "instrumentation.ts"));
+  const hasRoot = import_node_fs4.existsSync(import_node_path4.default.join(root, "instrumentation.ts"));
+  const hasSrc = import_node_fs4.existsSync(import_node_path4.default.join(root, "src", "instrumentation.ts"));
   if (!hasRoot && !hasSrc) {
-    console.warn("backmatter: add instrumentation.ts that imports .backmatter/sync — block schema sync will not run without it");
+    console.warn("backmatter: add instrumentation.ts that imports backmatter/sync — block schema sync will not run without it");
   }
 }
 function defaultLog(result, root) {
@@ -423,7 +702,7 @@ function defaultLog(result, root) {
 }
 function resolveLoaderOptions(options = {}) {
   return {
-    root: import_node_path3.default.resolve(options.root ?? process.cwd()),
+    root: import_node_path4.default.resolve(options.root ?? process.cwd()),
     outDir: options.outDir ?? DEFAULT_OUT_DIR,
     modelsDir: options.modelsDir ?? DEFAULT_DIRS.models,
     blocksDir: options.blocksDir ?? DEFAULT_DIRS.blocks,
@@ -442,7 +721,7 @@ function generateRegistry(options = {}) {
   return result;
 }
 function registryMatchers(loaderOptions) {
-  const rel = import_node_path3.default.relative(loaderOptions.root, import_node_path3.default.resolve(loaderOptions.root, loaderOptions.outDir)).split(import_node_path3.default.sep).join("/");
+  const rel = import_node_path4.default.relative(loaderOptions.root, import_node_path4.default.resolve(loaderOptions.root, loaderOptions.outDir)).split(import_node_path4.default.sep).join("/");
   const escaped = rel.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
   return {
     glob: `**/${rel}/*.ts`,
@@ -457,17 +736,30 @@ function withBackmatter(nextConfig = {}, options = {}) {
   const cfg = nextConfig;
   const existingTurbo = cfg.turbopack ?? {};
   const existingRules = existingTurbo.rules ?? {};
+  const existingAlias = existingTurbo.resolveAlias ?? {};
   const turbopackRule = { loaders: [use] };
   const turbopack = {
     ...existingTurbo,
+    resolveAlias: {
+      ...registryTurbopackAlias(loaderOptions.root, loaderOptions.outDir),
+      ...existingAlias
+    },
     rules: { ...existingRules, [glob]: turbopackRule }
   };
   const webpack = (config, context) => {
     config.module ??= {};
     config.module.rules ??= [];
     config.module.rules.push({ test, enforce: "pre", use: [use] });
+    config.resolve ??= {};
+    const prevAlias = config.resolve.alias;
+    const prev = prevAlias && typeof prevAlias === "object" && !Array.isArray(prevAlias) ? prevAlias : {};
+    config.resolve.alias = {
+      ...registryWebpackAlias(loaderOptions.root, loaderOptions.outDir),
+      ...prev
+    };
     return cfg.webpack ? cfg.webpack(config, context) : config;
   };
+  ensureRegistryTsconfig(loaderOptions.root, loaderOptions.outDir);
   const cacheComponents = cfg.cacheComponents ?? true;
   const transpilePackages = [
     ...new Set([...cfg.transpilePackages ?? [], "@backmatter/next", "@backmatter/core"])

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backmatter/next",
-  "version": "0.0.18",
+  "version": "0.0.19",
   "description": "Experimental Next.js adapter for Backmatter. APIs will break. Not ready for production.",
   "type": "module",
   "publishConfig": {

package/src/cached-doc.ts

@@ -1,4 +1,5 @@
 // packages/next/src/cached-doc.ts
+import type { ReactNode } from "react";
 import { contentCacheTags, listCacheTags, type BackmatterDoc, type BackmatterDocSummary } from "@backmatter/core";
 
 export type CacheFns = {
@@ -17,8 +18,15 @@ export type ListDocsFn = (filter?: {
   locale?: string;
 }) => Promise<BackmatterDocSummary[]>;
 
+export type PublishedRender = (
+  locale: string,
+  type: string,
+  slug: string,
+) => Promise<ReactNode>;
+
 let registeredGetDoc: GetDocFn | null = null;
 let registeredListDocs: ListDocsFn | null = null;
+let registeredPublishedRender: PublishedRender | null = null;
 
 /** Called from `createBackmatter` so `"use cache"` only closes over serializable args. */
 export function registerCachedDocGet(getDoc: GetDocFn): void {
@@ -29,6 +37,11 @@ export function registerCachedListDocs(listDocs: ListDocsFn): void {
   registeredListDocs = listDocs;
 }
 
+/** The catch-all registers the MDX/block render. `"use cache"` only receives ids. */
+export function registerPublishedRender(render: PublishedRender): void {
+  registeredPublishedRender = render;
+}
+
 async function loadCacheFns(): Promise<CacheFns> {
   try {
     const mod = (await import("next/cache" as string)) as CacheFns;
@@ -80,6 +93,27 @@ export async function getCachedDocs(
   return listDocs({ type, locale });
 }
 
+/**
+ * Finished published page (MDX body or composer blocks, plus layout).
+ * The cache entry is what a static prerender and a normal link prefetch store.
+ */
+export async function getCachedPublished(
+  locale: string,
+  type: string,
+  slug: string,
+  cache?: CacheFns,
+): Promise<ReactNode> {
+  "use cache";
+  const fns = cache ?? (await loadCacheFns());
+  fns.cacheLife("hours");
+  fns.cacheTag(...contentCacheTags(locale, type, slug));
+  const render = registeredPublishedRender;
+  if (!render) {
+    throw new Error("[backmatter] getCachedPublished called before a published render was registered");
+  }
+  return render(locale, type, slug);
+}
+
 /** Unwrap Next `params` inside `"use cache"` so Cache Components can prerender. */
 export async function cachedRouteParams<T extends object>(
   params: Promise<T> | T,

package/src/config.ts

@@ -1,8 +1,8 @@
 // packages/next/src/config.ts
 // `withBackmatter(nextConfig)` for next.config.{js,mjs,ts}.
 //
-// 1. Generates `.backmatter/` once when the config loads, so the first compile can
-//    resolve `import { cms } from ".backmatter"`.
+// 1. Generates `.backmatter/` once when the config loads, and aliases it to the
+//    `backmatter` import (`import { cms } from "backmatter"`).
 // 2. Registers `@backmatter/next/loader` for the registry files with Turbopack
 //    (Next 16 default) and webpack (`next build --webpack`). The loader declares
 //    `models/`, `blocks/`, `richtext/`, and `mdx/` as context dependencies, so the bundler's
@@ -16,6 +16,11 @@ import {
   generate,
   type GenerateResult,
 } from "@backmatter/core/generate";
+import {
+  ensureRegistryTsconfig,
+  registryTurbopackAlias,
+  registryWebpackAlias,
+} from "@backmatter/core/node/registry-import";
 import type { BackmatterLoaderOptions } from "./loader";
 
 export type WithBackmatterOptions = {
@@ -52,6 +57,7 @@ export type NextConfigLike = {
 
 export type WebpackConfigLike = {
   module?: { rules?: unknown[] } & Record<string, unknown>;
+  resolve?: { alias?: Record<string, unknown> } & Record<string, unknown>;
 } & Record<string, unknown>;
 
 export function warnMissingInstrumentation(root: string): void {
@@ -60,7 +66,7 @@ export function warnMissingInstrumentation(root: string): void {
   const hasSrc = existsSync(path.join(root, "src", "instrumentation.ts"));
   if (!hasRoot && !hasSrc) {
     console.warn(
-      "backmatter: add instrumentation.ts that imports .backmatter/sync — block schema sync will not run without it",
+      "backmatter: add instrumentation.ts that imports backmatter/sync — block schema sync will not run without it",
     );
   }
 }
@@ -141,9 +147,14 @@ export function withBackmatter<T extends object>(
   const cfg = nextConfig as T & NextConfigLike;
   const existingTurbo = (cfg.turbopack ?? {}) as Record<string, unknown>;
   const existingRules = (existingTurbo.rules ?? {}) as Record<string, unknown>;
+  const existingAlias = (existingTurbo.resolveAlias ?? {}) as Record<string, unknown>;
   const turbopackRule: TurbopackRule = { loaders: [use] };
   const turbopack = {
     ...existingTurbo,
+    resolveAlias: {
+      ...registryTurbopackAlias(loaderOptions.root, loaderOptions.outDir),
+      ...existingAlias,
+    },
     rules: { ...existingRules, [glob]: turbopackRule },
   };
 
@@ -152,17 +163,30 @@ export function withBackmatter<T extends object>(
     config.module.rules ??= [];
     // `enforce: "pre"` runs before Next's SWC loader; we return TypeScript, SWC compiles it.
     config.module.rules.push({ test, enforce: "pre", use: [use] });
+    config.resolve ??= {};
+    const prevAlias = config.resolve.alias;
+    const prev =
+      prevAlias && typeof prevAlias === "object" && !Array.isArray(prevAlias) ? prevAlias : {};
+    config.resolve.alias = {
+      ...registryWebpackAlias(loaderOptions.root, loaderOptions.outDir),
+      ...prev,
+    };
     return cfg.webpack ? cfg.webpack(config, context) : config;
   };
 
+  ensureRegistryTsconfig(loaderOptions.root, loaderOptions.outDir);
+
   const cacheComponents = cfg.cacheComponents ?? true;
+  // Published pages are static files. Partial prefetching would replace those
+  // files with one shared shell for every CMS URL, so a normal link would
+  // prefetch the shell instead of the finished page. Hosts can still opt in.
   const transpilePackages = [
     ...new Set([...(cfg.transpilePackages ?? []), "@backmatter/next", "@backmatter/core"]),
   ];
   return {
     ...nextConfig,
     cacheComponents,
-    partialPrefetching: cfg.partialPrefetching ?? cacheComponents,
+    partialPrefetching: cfg.partialPrefetching ?? false,
     transpilePackages,
     turbopack,
     webpack,

package/src/mdx-compile.ts

@@ -10,6 +10,25 @@ import remarkGfm from "remark-gfm";
 
 export type MdxComponents = Record<string, ComponentType<any>>;
 
+function UnknownMdx(props: { children?: ReactNode }) {
+  return props.children ?? null;
+}
+
+/**
+ * MDX copies `components` with object spread, which skips a Proxy.
+ * Fill each capitalized tag the host did not provide so one unknown tag
+ * does not fail the page render.
+ */
+function mdxComponentsWithFallback(source: string, components?: MdxComponents): MdxComponents {
+  const provided: MdxComponents = { ...components };
+  for (const match of source.matchAll(/<([A-Z][A-Za-z0-9]*)\b/g)) {
+    const name = match[1];
+    if (!name || provided[name]) continue;
+    provided[name] = UnknownMdx;
+  }
+  return provided;
+}
+
 export async function compileMdx(
   source: string,
   components?: MdxComponents,
@@ -22,7 +41,7 @@ export async function compileMdx(
       remarkPlugins: [remarkGfm],
       baseUrl: import.meta.url,
     });
-    return createElement(Content, { components });
+    return createElement(Content, { components: mdxComponentsWithFallback(source, components) });
   } catch (err) {
     const message = err instanceof Error ? err.message : "MDX compile failed";
     return createElement("pre", { role: "alert" }, message);

package/src/routes.ts

@@ -8,7 +8,7 @@ import { isRoutable, matchRoute, modelFormat, PREVIEW_CHECKOUT_QUERY, PREVIEW_CO
 import type { BackmatterClient } from "@backmatter/core/node/create-backmatter";
 import { fetchPreviewDoc } from "@backmatter/core/preview";
 import { renderDoc, type MdxComponents } from "./mdx-compile";
-import { cachedRouteParams } from "./cached-doc";
+import { cachedRouteParams, getCachedPublished, registerPublishedRender } from "./cached-doc";
 import { renderPage, type BlockComponents, type BlockFallbacks } from "./page-render";
 import { previewUnavailable } from "./preview-ui";
 
@@ -229,15 +229,30 @@ export function createCatchAll<Models extends readonly ModelDef[]>(
     }
   }
 
+  async function renderPublished(locale: string, type: string, slug: string): Promise<ReactNode> {
+    const doc = await cms.getDoc(locale, type, slug);
+    if (!doc) return null;
+    return createElement(
+      "div",
+      { "data-backmatter-published": "", style: { display: "contents" } },
+      await layoutDoc(doc, false),
+    );
+  }
+
+  async function publishedBody(locale: string, type: string, slug: string): Promise<ReactNode> {
+    registerPublishedRender(renderPublished);
+    const body = await getCachedPublished(locale, type, slug);
+    if (body == null) return failFor();
+    return body;
+  }
+
   const CmsRoute: CatchAllRoute["CmsRoute"] = async ({ params, searchParams }) => {
     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 (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);
+    return publishedBody(hit.locale, hit.type, hit.slug);
   };
 
   const PublishedRoute = async ({
@@ -249,13 +264,7 @@ export function createCatchAll<Models extends readonly ModelDef[]>(
     const resolved = await params;
     const hit = resolve(resolved[CATCH_ALL_PARAM]);
     if (!hit) return failFor();
-    const doc = await cms.getDoc(hit.locale, hit.type, hit.slug);
-    if (!doc) return failFor();
-    return createElement(
-      "div",
-      { "data-backmatter-published": "", style: { display: "contents" } },
-      await layoutDoc(doc, false),
-    );
+    return publishedBody(hit.locale, hit.type, hit.slug);
   };
 
   const PreviewBranch = async ({
@@ -286,11 +295,7 @@ export function createCatchAll<Models extends readonly ModelDef[]>(
     createElement(
       Fragment,
       null,
-      createElement(
-        Suspense,
-        { fallback: createElement("div", { "aria-busy": "true", style: { minHeight: "100vh" } }) },
-        createElement(PublishedRoute, props),
-      ),
+      createElement(PublishedRoute, props),
       createElement(Suspense, { fallback: null }, createElement(PreviewBranch, props)),
     );