@dreamtree-org/landing-kit 0.6.0 → 0.7.0

package/MIGRATION.md

@@ -106,3 +106,15 @@ Nothing changes for product landing pages. New, opt-in:
 - Apps that stored per-tenant brand colours elsewhere can move them into a theme with
   `validateTheme({ preset: 'custom', primary, accent })`.
 
+
+## 0.7.0 — serve-time page transforms (additive)
+
+Nothing changes unless you opt in:
+
+- `landingRoutes(app, { transformPage })`: `(body, { req, route, file, kind }) => string | null`
+  (may be async) runs on every prerendered page (`kind: 'page'`) and crawler file (`'crawler'`)
+  before the origin is filled in. Return the rewritten body, or null to serve the prerendered one;
+  a throw is logged and also serves the prerendered body. It runs per request, so cache inside it.
+- `fillPage(template, page)` from `/server`: the template fill `prerenderPages` does, as a string.
+  Keep a copy of the template (prerenderPages overwrites `landing.html`) and an SSR bundle to
+  re-render pages with live data, e.g. CMS-driven pricing.

package/README.md

@@ -266,7 +266,8 @@ to emit a graph without URLs. No ratings, reviews or prices are ever generated;
 
 | Function | Meaning |
 |---|---|
-| `landingRoutes(app, { dist, isPublicHost, hasSession, redirects, onSession, onPrivateHost, trailingSlash, rawFiles, manifest, cacheControl })` | serves `/` (visitors only, `Vary: Cookie`), every page in the manifest (default `landing-pages.json`; its paths are relative to its own directory), robots/sitemap/llms with the origin filled in, verification meta tags from env; 404s the raw files (`rawFiles: 'redirect'` 301s them to their page instead); `/x/` → 301 `/x` (`trailingSlash: 'serve'` answers both); `isPublicHost` may be async; a non-public host gets `Disallow: /` and, at `/`, `next()` or the app shell (`onPrivateHost: 'app-shell'`) |
+| `landingRoutes(app, { dist, isPublicHost, hasSession, redirects, onSession, onPrivateHost, trailingSlash, rawFiles, manifest, cacheControl, transformPage })` | serves `/` (visitors only, `Vary: Cookie`), every page in the manifest (default `landing-pages.json`; its paths are relative to its own directory), robots/sitemap/llms with the origin filled in, verification meta tags from env; 404s the raw files (`rawFiles: 'redirect'` 301s them to their page instead); `/x/` → 301 `/x` (`trailingSlash: 'serve'` answers both); `isPublicHost` may be async; a non-public host gets `Disallow: /` and, at `/`, `next()` or the app shell (`onPrivateHost: 'app-shell'`); `transformPage(body, { req, route, file, kind })` may rewrite a page or crawler file per request (e.g. live prices) and falls back to the prerendered body on null or a throw |
+| `fillPage(template, page)` | one page poured into the template, as a string: what `prerenderPages` writes. Pair it with `transformPage` to re-render a page with live data |
 | `prerenderPages({ dist, pages, files, homeFile, pagesDir, manifest })` | build step: fills `%TITLE% %DESCRIPTION% %PATH% %JSONLD% %HEAD% <!--landing-->` per page, writes `landing.html`, `landing-pages/…`, the manifest and crawler files; throws on an unfilled slot before writing anything |
 | `sessionCheck({ cookie: 'JWT_TOKEN', bearer, verify })` | `hasSession(req)` from your own JWT check |
 | `siteUrl(req)` · `verificationTags(env)` · `readCookie` · `fillSite` | helpers |

package/dist/server.cjs

@@ -43,6 +43,7 @@ __export(server_exports, {
   buildSitemap: () => buildSitemap,
   contentFacts: () => contentFacts,
   escapeHtml: () => escapeHtml,
+  fillPage: () => fillPage,
   fillSite: () => fillSite,
   jsonLdScript: () => jsonLdScript,
   landingRoutes: () => landingRoutes,
@@ -420,7 +421,8 @@ function landingRoutes(app, options = {}) {
     crawlerCache = "public, max-age=3600",
     privateRobots = PRIVATE_ROBOTS,
     appUrl,
-    env = process.env
+    env = process.env,
+    transformPage
   } = opts;
   if (!app || typeof app.get !== "function") throw new Error("landing-kit landingRoutes: pass the Express app as the first argument.");
   if (!dist) throw new Error('landing-kit landingRoutes: "dist" is missing \u2014 pass { dist: path.join(__dirname, "client/dist") }.');
@@ -452,9 +454,20 @@ function landingRoutes(app, options = {}) {
     res.set("Cache-Control", "no-cache");
     return res.sendFile(import_node_path.default.join(dist, "index.html"), (err) => err && next(err));
   };
-  const sendPage = (req, res, file) => {
+  const bodyFor = async (req, body, meta) => {
+    if (!transformPage) return body;
+    try {
+      const out = await transformPage(body, { req, ...meta });
+      return typeof out === "string" ? out : body;
+    } catch (err) {
+      console.error(`landing-kit transformPage failed on ${meta.route}:`, err?.message || err);
+      return body;
+    }
+  };
+  const sendPage = async (req, res, file, route) => {
+    const body = await bodyFor(req, read(file), { route, file, kind: "page" });
     res.set("Cache-Control", cacheControl);
-    res.type("html").send(fillSite(read(file), origin(req), { html: true, env }));
+    res.type("html").send(fillSite(body, origin(req), { html: true, env }));
   };
   app.get("/", guard(async (req, res, next) => {
     const file = routes["/"];
@@ -462,7 +475,7 @@ function landingRoutes(app, options = {}) {
     if (!await isPublic(req)) return onPrivateHost === "app-shell" ? appShell(res, next) : next();
     res.set("Vary", "Cookie");
     if (hasSession(req)) return onSession === "app-shell" ? appShell(res, next) : next();
-    sendPage(req, res, file);
+    await sendPage(req, res, file, "/");
   }));
   const byFile = Object.fromEntries(Object.entries(routes).map(([route, f]) => [`/${f}`, route]));
   const rawSet = /* @__PURE__ */ new Set([`/${manifestFile.split(import_node_path.default.sep).join("/")}`, ...Object.keys(byFile)]);
@@ -487,17 +500,18 @@ function landingRoutes(app, options = {}) {
         const file = routes[trimmed];
         if (!file || read(file) == null) return next();
         if (trimmed !== req.path && trailingSlash !== "serve") return res.redirect(301, trimmed + req.originalUrl.slice(req.path.length));
-        sendPage(req, res, file);
+        await sendPage(req, res, file, trimmed);
       })
     );
   }
   for (const [route, type] of Object.entries(CRAWLER_FILES)) {
     app.get(route, guard(async (req, res, next) => {
-      const body = await isPublic(req) ? read(route.slice(1)) : null;
-      if (body == null) {
+      const raw = await isPublic(req) ? read(route.slice(1)) : null;
+      if (raw == null) {
         if (route !== "/robots.txt") return next();
         return res.type("text/plain").send(privateRobots);
       }
+      const body = await bodyFor(req, raw, { route, file: route.slice(1), kind: "crawler" });
       res.set("Cache-Control", crawlerCache);
       res.type(type).send(fillSite(body, origin(req)));
     }));
@@ -507,21 +521,22 @@ function landingRoutes(app, options = {}) {
 function pageFile(p, { homeFile = "landing.html", pagesDir = "landing-pages" } = {}) {
   return p === "/" ? homeFile : import_node_path.default.posix.join(pagesDir, `${p.replace(/^\/+|\/+$/g, "")}.html`);
 }
+function fillPage(template, p, { slot = "<!--landing-->" } = {}) {
+  if (!template || !template.includes(slot)) throw new Error(`landing-kit prerenderPages: the template has no ${slot} slot for the page body.`);
+  for (const k of ["path", "html"]) if (p?.[k] == null) throw new Error(`landing-kit prerenderPages: page "${p?.path || "?"}" has no "${k}".`);
+  const esc = escapeHtml;
+  const jsonLd = p.jsonLd == null ? "" : typeof p.jsonLd === "string" ? p.jsonLd : JSON.stringify(p.jsonLd).replace(/</g, "\\u003c");
+  const out = template.replace(/%TITLE%/g, () => esc(p.title || "")).replace(/%DESCRIPTION%/g, () => esc(p.description || "")).replace(/%PATH%/g, () => p.path).replace("%JSONLD%", () => jsonLd).replace("%HEAD%", () => p.head || "").replace(slot, () => p.html);
+  const left = /%(TITLE|DESCRIPTION|PATH|JSONLD|HEAD)%/.exec(out);
+  if (left) throw new Error(`landing-kit prerenderPages: unfilled ${left[0]} on ${p.path}`);
+  return out;
+}
 function prerenderPages({ dist, template = "landing.html", pages, files = {}, homeFile = "landing.html", pagesDir = "landing-pages", manifest = "landing-pages.json", slot = "<!--landing-->" }) {
   if (!dist) throw new Error('landing-kit prerenderPages: "dist" is missing.');
   if (!Array.isArray(pages) || !pages.length) throw new Error('landing-kit prerenderPages: "pages" is missing \u2014 pass [{ path, html, title, description }].');
   const tpl = template.includes("<") ? template : import_node_fs.default.readFileSync(import_node_path.default.join(dist, template), "utf8");
   if (!tpl.includes(slot)) throw new Error(`landing-kit prerenderPages: the template has no ${slot} slot for the page body.`);
-  const esc = escapeHtml;
-  const outputs = [];
-  for (const p of pages) {
-    for (const k of ["path", "html"]) if (p[k] == null) throw new Error(`landing-kit prerenderPages: page "${p.path || "?"}" has no "${k}".`);
-    const jsonLd = p.jsonLd == null ? "" : typeof p.jsonLd === "string" ? p.jsonLd : JSON.stringify(p.jsonLd).replace(/</g, "\\u003c");
-    const out = tpl.replace(/%TITLE%/g, () => esc(p.title || "")).replace(/%DESCRIPTION%/g, () => esc(p.description || "")).replace(/%PATH%/g, () => p.path).replace("%JSONLD%", () => jsonLd).replace("%HEAD%", () => p.head || "").replace(slot, () => p.html);
-    const left = /%(TITLE|DESCRIPTION|PATH|JSONLD|HEAD)%/.exec(out);
-    if (left) throw new Error(`landing-kit prerenderPages: unfilled ${left[0]} on ${p.path}`);
-    outputs.push([p.path, pageFile(p.path, { homeFile, pagesDir }), out]);
-  }
+  const outputs = pages.map((p) => [p.path, pageFile(p.path, { homeFile, pagesDir }), fillPage(tpl, p, { slot })]);
   import_node_fs.default.rmSync(import_node_path.default.join(dist, pagesDir), { recursive: true, force: true });
   const map = {};
   let bytes = 0;
@@ -556,6 +571,7 @@ function prerenderPages({ dist, template = "landing.html", pages, files = {}, ho
   buildSitemap,
   contentFacts,
   escapeHtml,
+  fillPage,
   fillSite,
   jsonLdScript,
   landingRoutes,

package/dist/server.js

@@ -364,7 +364,8 @@ function landingRoutes(app, options = {}) {
     crawlerCache = "public, max-age=3600",
     privateRobots = PRIVATE_ROBOTS,
     appUrl,
-    env = process.env
+    env = process.env,
+    transformPage
   } = opts;
   if (!app || typeof app.get !== "function") throw new Error("landing-kit landingRoutes: pass the Express app as the first argument.");
   if (!dist) throw new Error('landing-kit landingRoutes: "dist" is missing \u2014 pass { dist: path.join(__dirname, "client/dist") }.');
@@ -396,9 +397,20 @@ function landingRoutes(app, options = {}) {
     res.set("Cache-Control", "no-cache");
     return res.sendFile(path.join(dist, "index.html"), (err) => err && next(err));
   };
-  const sendPage = (req, res, file) => {
+  const bodyFor = async (req, body, meta) => {
+    if (!transformPage) return body;
+    try {
+      const out = await transformPage(body, { req, ...meta });
+      return typeof out === "string" ? out : body;
+    } catch (err) {
+      console.error(`landing-kit transformPage failed on ${meta.route}:`, err?.message || err);
+      return body;
+    }
+  };
+  const sendPage = async (req, res, file, route) => {
+    const body = await bodyFor(req, read(file), { route, file, kind: "page" });
     res.set("Cache-Control", cacheControl);
-    res.type("html").send(fillSite(read(file), origin(req), { html: true, env }));
+    res.type("html").send(fillSite(body, origin(req), { html: true, env }));
   };
   app.get("/", guard(async (req, res, next) => {
     const file = routes["/"];
@@ -406,7 +418,7 @@ function landingRoutes(app, options = {}) {
     if (!await isPublic(req)) return onPrivateHost === "app-shell" ? appShell(res, next) : next();
     res.set("Vary", "Cookie");
     if (hasSession(req)) return onSession === "app-shell" ? appShell(res, next) : next();
-    sendPage(req, res, file);
+    await sendPage(req, res, file, "/");
   }));
   const byFile = Object.fromEntries(Object.entries(routes).map(([route, f]) => [`/${f}`, route]));
   const rawSet = /* @__PURE__ */ new Set([`/${manifestFile.split(path.sep).join("/")}`, ...Object.keys(byFile)]);
@@ -431,17 +443,18 @@ function landingRoutes(app, options = {}) {
         const file = routes[trimmed];
         if (!file || read(file) == null) return next();
         if (trimmed !== req.path && trailingSlash !== "serve") return res.redirect(301, trimmed + req.originalUrl.slice(req.path.length));
-        sendPage(req, res, file);
+        await sendPage(req, res, file, trimmed);
       })
     );
   }
   for (const [route, type] of Object.entries(CRAWLER_FILES)) {
     app.get(route, guard(async (req, res, next) => {
-      const body = await isPublic(req) ? read(route.slice(1)) : null;
-      if (body == null) {
+      const raw = await isPublic(req) ? read(route.slice(1)) : null;
+      if (raw == null) {
         if (route !== "/robots.txt") return next();
         return res.type("text/plain").send(privateRobots);
       }
+      const body = await bodyFor(req, raw, { route, file: route.slice(1), kind: "crawler" });
       res.set("Cache-Control", crawlerCache);
       res.type(type).send(fillSite(body, origin(req)));
     }));
@@ -451,21 +464,22 @@ function landingRoutes(app, options = {}) {
 function pageFile(p, { homeFile = "landing.html", pagesDir = "landing-pages" } = {}) {
   return p === "/" ? homeFile : path.posix.join(pagesDir, `${p.replace(/^\/+|\/+$/g, "")}.html`);
 }
+function fillPage(template, p, { slot = "<!--landing-->" } = {}) {
+  if (!template || !template.includes(slot)) throw new Error(`landing-kit prerenderPages: the template has no ${slot} slot for the page body.`);
+  for (const k of ["path", "html"]) if (p?.[k] == null) throw new Error(`landing-kit prerenderPages: page "${p?.path || "?"}" has no "${k}".`);
+  const esc = escapeHtml;
+  const jsonLd = p.jsonLd == null ? "" : typeof p.jsonLd === "string" ? p.jsonLd : JSON.stringify(p.jsonLd).replace(/</g, "\\u003c");
+  const out = template.replace(/%TITLE%/g, () => esc(p.title || "")).replace(/%DESCRIPTION%/g, () => esc(p.description || "")).replace(/%PATH%/g, () => p.path).replace("%JSONLD%", () => jsonLd).replace("%HEAD%", () => p.head || "").replace(slot, () => p.html);
+  const left = /%(TITLE|DESCRIPTION|PATH|JSONLD|HEAD)%/.exec(out);
+  if (left) throw new Error(`landing-kit prerenderPages: unfilled ${left[0]} on ${p.path}`);
+  return out;
+}
 function prerenderPages({ dist, template = "landing.html", pages, files = {}, homeFile = "landing.html", pagesDir = "landing-pages", manifest = "landing-pages.json", slot = "<!--landing-->" }) {
   if (!dist) throw new Error('landing-kit prerenderPages: "dist" is missing.');
   if (!Array.isArray(pages) || !pages.length) throw new Error('landing-kit prerenderPages: "pages" is missing \u2014 pass [{ path, html, title, description }].');
   const tpl = template.includes("<") ? template : fs.readFileSync(path.join(dist, template), "utf8");
   if (!tpl.includes(slot)) throw new Error(`landing-kit prerenderPages: the template has no ${slot} slot for the page body.`);
-  const esc = escapeHtml;
-  const outputs = [];
-  for (const p of pages) {
-    for (const k of ["path", "html"]) if (p[k] == null) throw new Error(`landing-kit prerenderPages: page "${p.path || "?"}" has no "${k}".`);
-    const jsonLd = p.jsonLd == null ? "" : typeof p.jsonLd === "string" ? p.jsonLd : JSON.stringify(p.jsonLd).replace(/</g, "\\u003c");
-    const out = tpl.replace(/%TITLE%/g, () => esc(p.title || "")).replace(/%DESCRIPTION%/g, () => esc(p.description || "")).replace(/%PATH%/g, () => p.path).replace("%JSONLD%", () => jsonLd).replace("%HEAD%", () => p.head || "").replace(slot, () => p.html);
-    const left = /%(TITLE|DESCRIPTION|PATH|JSONLD|HEAD)%/.exec(out);
-    if (left) throw new Error(`landing-kit prerenderPages: unfilled ${left[0]} on ${p.path}`);
-    outputs.push([p.path, pageFile(p.path, { homeFile, pagesDir }), out]);
-  }
+  const outputs = pages.map((p) => [p.path, pageFile(p.path, { homeFile, pagesDir }), fillPage(tpl, p, { slot })]);
   fs.rmSync(path.join(dist, pagesDir), { recursive: true, force: true });
   const map = {};
   let bytes = 0;
@@ -499,6 +513,7 @@ export {
   buildSitemap,
   contentFacts,
   escapeHtml,
+  fillPage,
   fillSite,
   jsonLdScript,
   landingRoutes,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreamtree-org/landing-kit",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "The shared marketing site and auth frame (AuthShell + brands) for every Dreamtree product: content-driven landing pages, login/signup shell, Express routes, prerender and SEO files.",
   "type": "module",
   "license": "MIT",

package/server.d.ts

@@ -31,13 +31,21 @@ export interface LandingRoutesOptions {
   privateRobots?: string;
   appUrl?: string;
   env?: Record<string, string | undefined>;
+  /**
+   * Runs on every page ('page') and crawler file ('crawler') before the origin is filled in,
+   * e.g. to re-render live prices. null/undefined or a throw serves the prerendered body.
+   */
+  transformPage?: (body: string, meta: { req: any; route: string; file: string; kind: 'page' | 'crawler' }) => string | null | undefined | Promise<string | null | undefined>;
 }
+export interface PrerenderPage { path: string; html: string; title?: string; description?: string; jsonLd?: unknown; head?: string }
+/** One page poured into the template: what prerenderPages writes, as a string. */
+export declare function fillPage(template: string, page: PrerenderPage, opts?: { slot?: string }): string;
 export declare function landingRoutes(app: any, options: LandingRoutesOptions | string): string[];
 export declare function pageFile(path: string, opts?: { homeFile?: string; pagesDir?: string }): string;
 export declare function prerenderPages(args: {
   dist: string;
   template?: string;
-  pages: Array<{ path: string; html: string; title?: string; description?: string; jsonLd?: unknown; head?: string }>;
+  pages: PrerenderPage[];
   files?: Record<string, string | null | undefined>;
   homeFile?: string; pagesDir?: string; manifest?: string; slot?: string;
 }): { manifest: Record<string, string>; bytes: number };