@backmatter/next 0.0.6

package/dist/loader.cjs

@@ -0,0 +1,349 @@
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toESMCache_node;
+var __toESMCache_esm;
+var __toESM = (mod, isNodeMode, target) => {
+  var canCache = mod != null && typeof mod === "object";
+  if (canCache) {
+    var cache = isNodeMode ? __toESMCache_node ??= new WeakMap : __toESMCache_esm ??= new WeakMap;
+    var cached = cache.get(mod);
+    if (cached)
+      return cached;
+  }
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  if (mod && typeof mod === "object" || typeof mod === "function") {
+    for (let key of __getOwnPropNames(mod))
+      if (!__hasOwnProp.call(to, key))
+        __defProp(to, key, {
+          get: __accessProp.bind(mod, key),
+          enumerable: true
+        });
+  }
+  if (canCache)
+    cache.set(mod, to);
+  return to;
+};
+var __toCommonJS = (from) => {
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __moduleCache;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/loader.ts
+var exports_loader = {};
+__export(exports_loader, {
+  default: () => backmatterLoader
+});
+module.exports = __toCommonJS(exports_loader);
+var import_node_path3 = __toESM(require("node:path"));
+
+// ../core/src/node/generate.ts
+var import_node_fs2 = require("node:fs");
+var import_node_path2 = __toESM(require("node:path"));
+
+// ../core/src/config.ts
+var DEFAULT_DIRS = {
+  models: "models",
+  blocks: "blocks",
+  mdx: "mdx",
+  layouts: "layouts"
+};
+
+// ../core/src/node/discover.ts
+var import_node_fs = require("node:fs");
+var import_node_path = __toESM(require("node:path"));
+var SOURCE_EXT = /\.(ts|tsx|js|jsx|mjs)$/;
+var IGNORED = /(\.test\.|\.spec\.|\.d\.ts$|\.stories\.)/;
+function toIdentifier(stem) {
+  const camel = stem.split(/[^A-Za-z0-9]+/).filter(Boolean).map((part, i) => i === 0 ? part : part[0].toUpperCase() + part.slice(1)).join("");
+  const safe = camel.replace(/^[^A-Za-z_$]/, (c) => `_${c}`);
+  return safe || "_";
+}
+function listSourceFiles(dir) {
+  if (!import_node_fs.existsSync(dir) || !import_node_fs.statSync(dir).isDirectory())
+    return [];
+  return import_node_fs.readdirSync(dir, { withFileTypes: true }).filter((e) => e.isFile() && SOURCE_EXT.test(e.name) && !IGNORED.test(e.name)).filter((e) => !e.name.startsWith("_") && !e.name.startsWith(".")).map((e) => import_node_path.default.join(dir, e.name)).sort();
+}
+function listModelFiles(root, modelsDir = "models") {
+  const files = listSourceFiles(import_node_path.default.resolve(root, modelsDir));
+  const seen = new Map;
+  return files.map((file) => {
+    const stem = import_node_path.default.basename(file).replace(SOURCE_EXT, "");
+    const importName = toIdentifier(stem);
+    const clash = seen.get(importName);
+    if (clash) {
+      throw new Error(`models/${import_node_path.default.basename(clash)} and models/${import_node_path.default.basename(file)} both map to "${importName}"`);
+    }
+    seen.set(importName, file);
+    return { file, stem, importName };
+  });
+}
+var JSX_TAG = /^[A-Z][A-Za-z0-9]*$/;
+var FALLBACK_STEM = /^([A-Z][A-Za-z0-9]*)\.fallback$/;
+function listPascalCaseFiles(root, dir) {
+  const files = [];
+  const skipped = [];
+  for (const file of listSourceFiles(import_node_path.default.resolve(root, dir))) {
+    const name = import_node_path.default.basename(file).replace(SOURCE_EXT, "");
+    if (FALLBACK_STEM.test(name))
+      continue;
+    if (JSX_TAG.test(name))
+      files.push({ file, name });
+    else
+      skipped.push(import_node_path.default.relative(root, file));
+  }
+  return { files, skipped };
+}
+function listBlockFallbackFiles(root, blocksDir = "blocks") {
+  const files = [];
+  for (const file of listSourceFiles(import_node_path.default.resolve(root, blocksDir))) {
+    const stem = import_node_path.default.basename(file).replace(SOURCE_EXT, "");
+    const match = FALLBACK_STEM.exec(stem);
+    if (match)
+      files.push({ file, name: match[1] });
+  }
+  return files.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+}
+function listLayoutFiles(root, layoutsDir = "layouts") {
+  return listModelFiles(root, layoutsDir);
+}
+function listBlockFiles(root, blocksDir = "blocks") {
+  const { files, skipped } = listPascalCaseFiles(root, blocksDir);
+  return { blocks: files, skipped };
+}
+function listMdxFiles(root, mdxDir = "mdx") {
+  const { files, skipped } = listPascalCaseFiles(root, mdxDir);
+  return { blocks: files, skipped };
+}
+
+// ../core/src/node/generate.ts
+var GENERATED_HEADER = "// Generated by backmatter — do not edit. Re-run `backmatter generate`.";
+var DEFAULT_OUT_DIR = ".backmatter";
+var CONFIG_FILES = ["backmatter.config.ts", "backmatter.config.mts", "backmatter.config.js", "backmatter.config.mjs"];
+function importSpecifier(fromDir, file) {
+  const rel = import_node_path2.default.relative(fromDir, file).split(import_node_path2.default.sep).join("/").replace(/\.(ts|tsx|mts|js|jsx|mjs)$/, "");
+  return rel.startsWith(".") ? rel : `./${rel}`;
+}
+function findConfigFile(root) {
+  for (const name of CONFIG_FILES) {
+    const full = import_node_path2.default.join(root, name);
+    if (import_node_fs2.existsSync(full))
+      return full;
+  }
+  return null;
+}
+function detectSdk(root) {
+  try {
+    const pkg = JSON.parse(import_node_fs2.readFileSync(import_node_path2.default.join(root, "package.json"), "utf-8"));
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (deps["@backmatter/next"])
+      return "@backmatter/next";
+  } catch {}
+  return "@backmatter/core/node";
+}
+function renderModelsBarrel(input) {
+  const lines = [GENERATED_HEADER, `import { createBackmatter } from "${input.sdk}";`];
+  if (input.configFile) {
+    lines.push(`import config from "${importSpecifier(input.outDir, input.configFile)}";`);
+  } else {
+    lines.push("const config = {};");
+  }
+  for (const m of input.models) {
+    lines.push(`import ${m.importName} from "${importSpecifier(input.outDir, m.file)}";`);
+  }
+  lines.push("");
+  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 });");
+  return `${lines.join(`
+`)}
+`;
+}
+function renderSyncBarrel(input) {
+  const lines = [GENERATED_HEADER, `import { createBackmatter } from "${input.sdk}";`];
+  if (input.configFile) {
+    lines.push(`import config from "${importSpecifier(input.outDir, input.configFile)}";`);
+  } else {
+    lines.push("const config = {};");
+  }
+  for (const m of input.models) {
+    lines.push(`import ${m.importName} from "${importSpecifier(input.outDir, m.file)}";`);
+  }
+  for (const b of input.blocks) {
+    lines.push(`import ${b.name} from "${importSpecifier(input.outDir, b.file)}";`);
+  }
+  lines.push("");
+  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(`export const blocks = [${input.blocks.map((b) => b.name).join(", ")}] as const;`);
+  lines.push("");
+  lines.push("/** Typed content client: cms.query.{type}, cms.getDoc, cms.listDocs. */");
+  lines.push("export const cms = createBackmatter({ ...config, models, blocks });");
+  return `${lines.join(`
+`)}
+`;
+}
+function renderMdxBarrel(input) {
+  const lines = [GENERATED_HEADER];
+  for (const b of input.mdx) {
+    lines.push(`import ${b.name} from "${importSpecifier(input.outDir, b.file)}";`);
+  }
+  lines.push("");
+  lines.push("/** MDX component map: <Hero /> in content resolves to mdx/Hero.tsx. */");
+  const names = input.mdx.map((b) => b.name).join(", ");
+  lines.push(`export const components = ${names ? `{ ${names} }` : "{}"};`);
+  return `${lines.join(`
+`)}
+`;
+}
+function renderBlocksBarrel(input) {
+  const lines = [GENERATED_HEADER, ""];
+  lines.push('/** Composer loaders: JSON `{ type: "Hero" }` → dynamic import of blocks/Hero.tsx. */');
+  const entries = [...input.blocks].sort((a, b) => a.name.localeCompare(b.name)).map((b) => `${b.name}: Object.assign(() => import("${importSpecifier(input.outDir, b.file)}"), { $$backmatterLoader: true })`);
+  lines.push(`export const blockLoaders = ${entries.length ? `{ ${entries.join(", ")} }` : "{}"};`);
+  return `${lines.join(`
+`)}
+`;
+}
+function renderBlockFallbacksBarrel(input) {
+  const lines = [GENERATED_HEADER];
+  for (const b of input.fallbacks) {
+    lines.push(`import ${b.name} from "${importSpecifier(input.outDir, b.file)}";`);
+  }
+  lines.push("");
+  const names = input.fallbacks.map((b) => b.name).join(", ");
+  lines.push(`export const blockFallbacks = ${names ? `{ ${names} }` : "{}"};`);
+  return `${lines.join(`
+`)}
+`;
+}
+function renderLayoutsBarrel(input) {
+  const lines = [GENERATED_HEADER];
+  for (const layout of input.layouts) {
+    lines.push(`import ${layout.importName} from "${importSpecifier(input.outDir, layout.file)}";`);
+  }
+  lines.push("");
+  lines.push("/** Per-type wrappers: layouts/{type}.tsx wraps that model's catch-all body. */");
+  const entries = input.layouts.map((l) => l.importName === l.stem ? l.stem : `${JSON.stringify(l.stem)}: ${l.importName}`);
+  lines.push(`export const layouts = ${entries.length ? `{ ${entries.join(", ")} }` : "{}"};`);
+  return `${lines.join(`
+`)}
+`;
+}
+function differsOnDisk(file, content) {
+  return !import_node_fs2.existsSync(file) || import_node_fs2.readFileSync(file, "utf-8") !== content;
+}
+var REGISTRY_FILES = [
+  "index.ts",
+  "blocks.ts",
+  "block-fallbacks.ts",
+  "mdx.ts",
+  "layouts.ts",
+  "sync.ts"
+];
+function generate(options) {
+  const root = import_node_path2.default.resolve(options.root);
+  const outDir = import_node_path2.default.resolve(root, options.outDir ?? DEFAULT_OUT_DIR);
+  const models = listModelFiles(root, options.modelsDir ?? DEFAULT_DIRS.models);
+  const { blocks, skipped: skippedBlocks } = listBlockFiles(root, options.blocksDir ?? DEFAULT_DIRS.blocks);
+  const fallbacks = listBlockFallbackFiles(root, options.blocksDir ?? DEFAULT_DIRS.blocks);
+  const { blocks: mdx, skipped: skippedMdx } = listMdxFiles(root, options.mdxDir ?? DEFAULT_DIRS.mdx);
+  const layouts = listLayoutFiles(root, options.layoutsDir ?? DEFAULT_DIRS.layouts);
+  const sdk = options.sdk ?? detectSdk(root);
+  const configFile = findConfigFile(root);
+  const write = options.write ?? true;
+  const rendered = {
+    "index.ts": renderModelsBarrel({ outDir, models, configFile, sdk }),
+    "blocks.ts": renderBlocksBarrel({ outDir, blocks }),
+    "block-fallbacks.ts": renderBlockFallbacksBarrel({ outDir, fallbacks }),
+    "mdx.ts": renderMdxBarrel({ outDir, mdx }),
+    "layouts.ts": renderLayoutsBarrel({ outDir, layouts }),
+    "sync.ts": renderSyncBarrel({ outDir, models, blocks, configFile, sdk })
+  };
+  const outputs = REGISTRY_FILES.map((name) => {
+    const file = import_node_path2.default.join(outDir, name);
+    const content = rendered[name];
+    const changed = differsOnDisk(file, content);
+    if (changed && write) {
+      import_node_fs2.mkdirSync(import_node_path2.default.dirname(file), { recursive: true });
+      import_node_fs2.writeFileSync(file, content);
+    }
+    return { file, rel: import_node_path2.default.relative(root, file).split(import_node_path2.default.sep).join("/"), content, changed };
+  });
+  return {
+    outputs,
+    files: outputs.map((o) => o.rel),
+    changed: outputs.filter((o) => o.changed).map((o) => o.rel),
+    models,
+    blocks,
+    mdx,
+    layouts,
+    skippedBlocks,
+    skippedMdx,
+    configFile
+  };
+}
+
+// src/loader.ts
+function backmatterLoader(source) {
+  const options = this.getOptions();
+  const root = import_node_path3.default.resolve(options.root);
+  const modelsDir = import_node_path3.default.resolve(root, options.modelsDir);
+  const blocksDir = import_node_path3.default.resolve(root, options.blocksDir);
+  const mdxDir = import_node_path3.default.resolve(root, options.mdxDir);
+  const layoutsDir = import_node_path3.default.resolve(root, options.layoutsDir);
+  this.addContextDependency(modelsDir);
+  this.addContextDependency(blocksDir);
+  this.addContextDependency(mdxDir);
+  this.addContextDependency(layoutsDir);
+  this.cacheable?.(true);
+  const result = generate({
+    root,
+    outDir: options.outDir,
+    modelsDir: options.modelsDir,
+    blocksDir: options.blocksDir,
+    mdxDir: options.mdxDir,
+    layoutsDir: options.layoutsDir,
+    sdk: options.sdk
+  });
+  if (result.configFile)
+    this.addDependency(result.configFile);
+  const output = result.outputs.find((o) => import_node_path3.default.resolve(o.file) === import_node_path3.default.resolve(this.resourcePath));
+  return output ? output.content : source;
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@backmatter/next",
+  "version": "0.0.6",
+  "description": "Experimental Next.js adapter for Backmatter. APIs will break. Not ready for production.",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./preview": "./src/preview.ts",
+    "./devbar": "./src/devbar.tsx",
+    "./mdx": "./src/mdx.ts",
+    "./mdx/client": "./src/mdx-client.tsx",
+    "./config": {
+      "types": "./src/config.ts",
+      "default": "./dist/config.cjs"
+    },
+    "./loader": {
+      "types": "./src/loader.ts",
+      "default": "./dist/loader.cjs"
+    },
+    "./routes": "./src/routes.ts",
+    "./revalidate": "./src/revalidate.ts",
+    "./preview-route": "./src/preview-route.ts",
+    "./proxy": "./src/proxy.ts",
+    "./middleware": "./src/middleware.ts",
+    "./page": "./src/page-render.ts"
+  },
+  "files": [
+    "src",
+    "dist",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx"
+  ],
+  "scripts": {
+    "build": "bun build src/config.ts src/loader.ts --outdir dist --target node --format cjs --entry-naming \"[name].cjs\"",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@backmatter/core": "^0.0.6",
+    "@mdx-js/mdx": "^3.1.1",
+    "remark-gfm": "^4.0.1"
+  },
+  "peerDependencies": {
+    "next": ">=16.3.0",
+    "react": ">=19",
+    "react-dom": ">=19"
+  },
+  "peerDependenciesMeta": {
+    "next": { "optional": true }
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0"
+  }
+}

package/src/cached-doc.ts

@@ -0,0 +1,55 @@
+// packages/next/src/cached-doc.ts
+import { contentCacheTags, type BackmatterDoc } from "@backmatter/core";
+
+export type CacheFns = {
+  cacheLife: (profile: string) => void;
+  cacheTag: (...tags: string[]) => void;
+};
+
+export type GetDocFn = (
+  locale: string,
+  type: string,
+  slug: string,
+) => Promise<BackmatterDoc | null>;
+
+let registeredGetDoc: GetDocFn | null = null;
+
+/** Called from `createCatchAll` so `"use cache"` only closes over serializable args. */
+export function registerCachedDocGet(getDoc: GetDocFn): void {
+  registeredGetDoc = getDoc;
+}
+
+async function loadCacheFns(): Promise<CacheFns> {
+  try {
+    const mod = (await import("next/cache" as string)) as CacheFns;
+    return {
+      cacheLife: (profile) => {
+        if (!process.env.__NEXT_USE_CACHE) return;
+        mod.cacheLife(profile);
+      },
+      cacheTag: (...tags) => {
+        if (!process.env.__NEXT_USE_CACHE) return;
+        mod.cacheTag(...tags);
+      },
+    };
+  } catch {
+    return { cacheLife: () => {}, cacheTag: () => {} };
+  }
+}
+
+export async function getCachedDoc(
+  locale: string,
+  type: string,
+  slug: string,
+  cache?: CacheFns,
+): Promise<BackmatterDoc | null> {
+  "use cache";
+  const fns = cache ?? (await loadCacheFns());
+  fns.cacheLife("hours");
+  fns.cacheTag(...contentCacheTags(locale, type, slug));
+  const getDoc = registeredGetDoc;
+  if (!getDoc) {
+    throw new Error("[backmatter] getCachedDoc called before createCatchAll registered getDoc");
+  }
+  return getDoc(locale, type, slug);
+}

package/src/config.ts

@@ -0,0 +1,160 @@
+// 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"`.
+// 2. Registers `@backmatter/next/loader` for the registry files with Turbopack
+//    (Next 16 default) and webpack (`next build --webpack`). The loader declares
+//    `models/`, `blocks/`, and `mdx/` as context dependencies, so the bundler's
+//    own file watcher keeps the registry fresh — no polling, no second watcher process.
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { DEFAULT_DIRS } from "@backmatter/core/generate";
+import {
+  DEFAULT_OUT_DIR,
+  detectSdk,
+  generate,
+  type GenerateResult,
+} from "@backmatter/core/generate";
+import type { BackmatterLoaderOptions } from "./loader";
+
+export type WithBackmatterOptions = {
+  /** Customer repo root. Default: process.cwd(). */
+  root?: string;
+  outDir?: string;
+  modelsDir?: string;
+  blocksDir?: string;
+  mdxDir?: string;
+  layoutsDir?: string;
+  /** Called after the boot-time generation. Default: log what changed. */
+  onGenerate?: (result: GenerateResult) => void;
+};
+
+export const LOADER = "@backmatter/next/loader";
+const SDK = "@backmatter/next";
+
+type TurbopackRule = { loaders: Array<{ loader: string; options: Record<string, unknown> }> };
+
+/**
+ * The slice of NextConfig we touch; kept local so `next` stays optional.
+ * Deliberately loose so the real `NextConfig` (whose `TurbopackOptions` has no
+ * index signature and whose `webpack` context is a concrete type) is assignable.
+ */
+export type NextConfigLike = {
+  cacheComponents?: boolean;
+  partialPrefetching?: boolean | "unstable_eager";
+  turbopack?: Record<string, unknown>;
+  webpack?: ((config: WebpackConfigLike, context: any) => WebpackConfigLike) | null;
+} & Record<string, unknown>;
+
+export type WebpackConfigLike = {
+  module?: { rules?: unknown[] } & Record<string, unknown>;
+} & Record<string, unknown>;
+
+export function warnMissingInstrumentation(root: string): void {
+  if (detectSdk(root) !== "@backmatter/next") return;
+  const hasRoot = existsSync(path.join(root, "instrumentation.ts"));
+  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",
+    );
+  }
+}
+
+function defaultLog(result: GenerateResult, root: string): void {
+  for (const file of result.changed) console.log(`backmatter: wrote ${file}`);
+  for (const skipped of result.skippedBlocks) {
+    console.warn(`backmatter: skipped ${skipped} (block file names must be PascalCase)`);
+  }
+  for (const skipped of result.skippedMdx) {
+    console.warn(`backmatter: skipped ${skipped} (MDX file names must be PascalCase)`);
+  }
+  warnMissingInstrumentation(root);
+}
+
+export function resolveLoaderOptions(options: WithBackmatterOptions = {}): BackmatterLoaderOptions {
+  return {
+    root: path.resolve(options.root ?? process.cwd()),
+    outDir: options.outDir ?? DEFAULT_OUT_DIR,
+    modelsDir: options.modelsDir ?? DEFAULT_DIRS.models,
+    blocksDir: options.blocksDir ?? DEFAULT_DIRS.blocks,
+    mdxDir: options.mdxDir ?? DEFAULT_DIRS.mdx,
+    layoutsDir: options.layoutsDir ?? DEFAULT_DIRS.layouts,
+    sdk: SDK,
+  };
+}
+
+/** Generate once. Safe to call repeatedly; only changed files are rewritten. */
+export function generateRegistry(options: WithBackmatterOptions = {}): GenerateResult {
+  const loaderOptions = resolveLoaderOptions(options);
+  const result = generate(loaderOptions);
+  const root = loaderOptions.root;
+  (options.onGenerate ?? ((r) => defaultLog(r, root)))(result);
+  return result;
+}
+
+/** Glob (Turbopack) and RegExp (webpack) matching the registry files. */
+export function registryMatchers(loaderOptions: BackmatterLoaderOptions): { glob: string; test: RegExp } {
+  const rel = path
+    .relative(loaderOptions.root, path.resolve(loaderOptions.root, loaderOptions.outDir))
+    .split(path.sep)
+    .join("/");
+  const escaped = rel.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return {
+    glob: `**/${rel}/*.ts`,
+    test: new RegExp(`(^|[\\\\/])${escaped.replace(/\//g, "[\\\\/]")}[\\\\/](index|blocks|block-fallbacks|mdx|layouts|sync)\\.ts$`),
+  };
+}
+
+/**
+ * Wrap your Next config:
+ *
+ * ```ts
+ * // next.config.ts
+ * import { withBackmatter } from "@backmatter/next/config";
+ * export default withBackmatter({ reactStrictMode: true });
+ * ```
+ */
+export type WithBackmatterResult<T extends object> = Omit<T, "turbopack" | "webpack"> & {
+  cacheComponents: boolean;
+  partialPrefetching: boolean | "unstable_eager";
+  turbopack: Record<string, unknown>;
+  webpack: NonNullable<NextConfigLike["webpack"]>;
+};
+
+export function withBackmatter<T extends object>(
+  nextConfig: T = {} as T,
+  options: WithBackmatterOptions = {},
+): WithBackmatterResult<T> {
+  const loaderOptions = resolveLoaderOptions(options);
+  generateRegistry(options);
+  const { glob, test } = registryMatchers(loaderOptions);
+  const use = { loader: LOADER, options: loaderOptions as unknown as Record<string, unknown> };
+
+  const cfg = nextConfig as T & NextConfigLike;
+  const existingTurbo = (cfg.turbopack ?? {}) as Record<string, unknown>;
+  const existingRules = (existingTurbo.rules ?? {}) as Record<string, unknown>;
+  const turbopackRule: TurbopackRule = { loaders: [use] };
+  const turbopack = {
+    ...existingTurbo,
+    rules: { ...existingRules, [glob]: turbopackRule },
+  };
+
+  const webpack: NonNullable<NextConfigLike["webpack"]> = (config, context) => {
+    config.module ??= {};
+    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] });
+    return cfg.webpack ? cfg.webpack(config, context) : config;
+  };
+
+  const cacheComponents = cfg.cacheComponents ?? true;
+  return {
+    ...nextConfig,
+    cacheComponents,
+    partialPrefetching: cfg.partialPrefetching ?? cacheComponents,
+    turbopack,
+    webpack,
+  };
+}

package/src/create-backmatter.ts

@@ -0,0 +1,15 @@
+// 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"`.
+import {
+  createBackmatter as createCore,
+  type CreateBackmatterOptions,
+  type BackmatterClient,
+} from "@backmatter/core/node/create-backmatter";
+import type { ModelDef } from "@backmatter/core";
+
+export function createBackmatter<const Models extends readonly ModelDef[]>(
+  options: CreateBackmatterOptions<Models>,
+): BackmatterClient<Models> {
+  return createCore({ ...options, taggedApiFetch: true });
+}