feat(docs): server-render the blog (no rebuild needed for new posts)

apps/fumadocs/src/lib/notra-runtime.ts

@@ -0,0 +1,71 @@
+import { createServerFn } from "@tanstack/react-start";
+
+import type { BlogPost } from "./blog-types";
+import type { NotraPostInput } from "../../scripts/notra-content";
+
+export type BlogPostDetail = {
+  post: BlogPost;
+  html: string;
+};
+
+// Server-only: fetch published posts from Notra at request time and map them to
+// the blog shape. The blog routes are not prerendered (see vite.config.ts), so
+// these run inside the Vercel SSR function and pick up new posts without a
+// rebuild. Dynamic imports keep @usenotra/sdk and the Markdown renderer out of
+// the client bundle; the API key stays server-side.
+async function fetchBlogData(): Promise<{ posts: BlogPost[]; bodies: Record<string, string> }> {
+  const apiKey = process.env.NOTRA_API_KEY?.trim();
+  if (!apiKey) return { posts: [], bodies: {} };
+
+  const [{ Notra }, { mapNotraPost }] = await Promise.all([
+    import("@usenotra/sdk"),
+    import("../../scripts/notra-content"),
+  ]);
+
+  const notra = new Notra({ bearerAuth: apiKey });
+  const raw: NotraPostInput[] = [];
+  let page = 1;
+
+  for (;;) {
+    const response = await notra.content.listPosts({
+      status: "published",
+      sort: "desc",
+      limit: 100,
+      page,
+    });
+    raw.push(...(response.posts as NotraPostInput[]));
+
+    const nextPage = response.pagination?.nextPage;
+    if (!nextPage) break;
+    page = nextPage;
+  }
+
+  const seenSlugs = new Set<string>();
+  const posts: BlogPost[] = [];
+  const bodies: Record<string, string> = {};
+
+  for (const item of raw) {
+    const mapped = mapNotraPost(item, seenSlugs);
+    if (!mapped) continue;
+
+    posts.push(mapped.post);
+    bodies[mapped.post.slug] = mapped.html;
+  }
+
+  posts.sort((a, b) => b.publishedAt.localeCompare(a.publishedAt));
+  return { posts, bodies };
+}
+
+export const getBlogPostsServerFn = createServerFn({ method: "GET" }).handler(async () => {
+  return (await fetchBlogData()).posts;
+});
+
+export const getBlogPostServerFn = createServerFn({ method: "GET" })
+  .inputValidator((slug: string) => slug)
+  .handler(async ({ data: slug }): Promise<BlogPostDetail | null> => {
+    const { posts, bodies } = await fetchBlogData();
+    const post = posts.find((item) => item.slug === slug);
+    if (!post) return null;
+
+    return { post, html: bodies[post.slug] ?? "" };
+  });

apps/fumadocs/src/routes/blog/$slug.tsx

@@ -2,15 +2,9 @@ import { createFileRoute, Link, notFound } from "@tanstack/react-router";
 import { HomeLayout } from "fumadocs-ui/layouts/home";
 import { ArrowRight } from "lucide-react";
 
-import {
-  formatBlogDate,
-  getBlogPost,
-  getBlogPostMetaTitle,
-  getBlogPostUrl,
-  type BlogPost,
-} from "@/lib/blog";
+import { formatBlogDate, getBlogPostMetaTitle, getBlogPostUrl, type BlogPost } from "@/lib/blog";
 import { baseOptions } from "@/lib/layout.shared";
-import { notraPostBodies } from "@/lib/notra-posts.generated";
+import { getBlogPostServerFn } from "@/lib/notra-runtime";
 import { siteUrl } from "@/lib/shared";
 
 type BlogPostLoaderData = {
@@ -19,8 +13,8 @@ type BlogPostLoaderData = {
 };
 
 export const Route = createFileRoute("/blog/$slug")({
-  head: ({ params }) => {
-    const post = getBlogPost(params.slug, { includeFuture: true });
+  head: ({ params, loaderData }) => {
+    const post = (loaderData as BlogPostLoaderData | undefined)?.post;
     const title = post ? getBlogPostMetaTitle(post.title) : "Email SDK Blog";
     const description = post?.description ?? "Email SDK blog post.";
     const canonicalUrl = `${siteUrl}${getBlogPostUrl(params.slug)}`;
@@ -110,22 +104,23 @@ export const Route = createFileRoute("/blog/$slug")({
     };
   },
   component: BlogPostPage,
-  loader: ({ params }) => {
-    const post = getBlogPost(params.slug, { includeFuture: true });
-    if (!post) throw notFound();
+  loader: async ({ params }) => {
+    const detail = await getBlogPostServerFn({ data: params.slug });
+    if (!detail) throw notFound();
 
-    return {
-      post,
-      html: notraPostBodies[post.slug] ?? "",
-    };
+    return detail;
   },
+  headers: () => ({
+    // Edge-cache the SSR'd post; updates and new posts appear within s-maxage, no rebuild.
+    "Cache-Control": "public, max-age=0, s-maxage=60, stale-while-revalidate=600",
+  }),
 });
 
 function BlogPostPage() {
   const { html, post } = Route.useLoaderData() as BlogPostLoaderData;
 
-  // `html` is the post body, rendered from the post's Markdown and sanitized at
-  // build time in scripts/notra-content.ts, so it is safe to inject here.
+  // `html` is the post body, rendered from the post's Markdown and sanitized
+  // server-side in scripts/notra-content.ts, so it is safe to inject here.
   return (
     <HomeLayout {...baseOptions()}>
       <main className="border-b border-fd-border bg-fd-background text-fd-foreground">

apps/fumadocs/src/routes/blog/index.tsx

@@ -2,8 +2,9 @@ import { createFileRoute, Link } from "@tanstack/react-router";
 import { HomeLayout } from "fumadocs-ui/layouts/home";
 import { ArrowRight } from "lucide-react";
 
-import { formatBlogDate, getPublishedBlogPosts, type BlogPost } from "@/lib/blog";
+import { formatBlogDate, type BlogPost } from "@/lib/blog";
 import { baseOptions } from "@/lib/layout.shared";
+import { getBlogPostsServerFn } from "@/lib/notra-runtime";
 import { appName, siteOgImageUrl, siteUrl } from "@/lib/shared";
 
 export const Route = createFileRoute("/blog/")({
@@ -75,7 +76,11 @@ export const Route = createFileRoute("/blog/")({
       links: [{ rel: "canonical", href: `${siteUrl}/blog` }],
     };
   },
-  loader: () => getPublishedBlogPosts(),
+  loader: () => getBlogPostsServerFn(),
+  headers: () => ({
+    // Edge-cache the SSR'd page; new Notra posts appear within s-maxage without a rebuild.
+    "Cache-Control": "public, max-age=0, s-maxage=60, stale-while-revalidate=600",
+  }),
   component: BlogIndex,
 });
 

apps/fumadocs/src/routes/og/blog/$.ts

@@ -1,20 +1,25 @@
 import { createFileRoute } from "@tanstack/react-router";
 
-import { getBlogPost } from "@/lib/blog";
+import type { BlogPost } from "@/lib/blog";
+import { getBlogPostServerFn } from "@/lib/notra-runtime";
 import { appName, siteUrl } from "@/lib/shared";
 
 export const Route = createFileRoute("/og/blog/$")({
   server: {
     handlers: {
-      GET({ params }) {
+      async GET({ params }) {
         const slug = params._splat?.replace(/\.svg$/, "");
-        const post = slug ? getBlogPost(slug, { includeFuture: true }) : undefined;
 
-        if (!post || params._splat === slug) {
+        if (!slug || params._splat === slug) {
           return new Response("Not found", { status: 404 });
         }
 
-        return new Response(renderBlogOgImage(post), {
+        const detail = await getBlogPostServerFn({ data: slug });
+        if (!detail) {
+          return new Response("Not found", { status: 404 });
+        }
+
+        return new Response(renderBlogOgImage(detail.post), {
           headers: {
             "cache-control": "public, max-age=86400, stale-while-revalidate=604800",
             "content-type": "image/svg+xml; charset=utf-8",
@@ -25,7 +30,7 @@ export const Route = createFileRoute("/og/blog/$")({
   },
 });
 
-type OgPost = NonNullable<ReturnType<typeof getBlogPost>>;
+type OgPost = BlogPost;
 
 const palettes = [
   ["#121214", "#f2d492", "#6ee7b7", "#8aa8ff"],

apps/fumadocs/vite.config.ts

@@ -8,7 +8,6 @@ import mdx from "fumadocs-mdx/vite";
 import { nitro } from "nitro/vite";
 import { defineConfig, loadEnv } from "vite";
 
-import { getAllBlogPosts, getBlogPostImageUrl, getBlogPostUrl } from "./src/lib/blog";
 import { docsVersions, getDocsVersionHref } from "./src/lib/versions";
 
 function collectContentPages(dir: string) {
@@ -80,6 +79,11 @@ export default defineConfig(({ mode }) => {
         prerender: {
           enabled: true,
           crawlLinks: true,
+          // Blog routes (/blog, /blog/$slug, /og/blog/*) render on-demand via the
+          // SSR function so new Notra posts appear without a rebuild; everything
+          // else stays prerendered to static HTML.
+          filter: ({ path }: { path: string }) =>
+            !path.startsWith("/blog") && !path.startsWith("/og/blog"),
         },
 
         pages: [
@@ -89,9 +93,6 @@ export default defineConfig(({ mode }) => {
           {
             path: "/docs",
           },
-          {
-            path: "/blog",
-          },
           {
             path: "/about",
           },
@@ -104,12 +105,6 @@ export default defineConfig(({ mode }) => {
           {
             path: "/terms",
           },
-          ...getAllBlogPosts().map((post) => ({
-            path: getBlogPostUrl(post.slug),
-          })),
-          ...getAllBlogPosts().map((post) => ({
-            path: getBlogPostImageUrl(post.slug),
-          })),
           ...versionedDocsPages,
           {
             path: "/api/search",

vercel.json

@@ -1,5 +1,5 @@
 {
-  "outputDirectory": "apps/fumadocs/.vercel/output/static",
+  "outputDirectory": "apps/fumadocs/.vercel/output",
   "rewrites": [
     {
       "source": "/",