perf(og): render blog OG/Instagram images on-demand, not at build

app/blog/instagram/[...slug]/route.tsx

@@ -1,23 +1,43 @@
+// Dynamic 4:5 Instagram image for a blog post, as a Route Handler. See
+// app/blog/og/[...slug] for the on-demand-ISR / static-export split.
+
 import { generateBlogStaticParams } from 'utils/blog/generateBlogStaticParams';
 import { getBlogPost } from 'utils/blog/getBlogPost';
 import { renderBlogInstagramImage } from 'utils/og/blogInstagramImage';
 
+const IS_EXPORT = process.env.EXPORT_MODE === 'static';
+
 export const dynamic = 'force-static';
-export const dynamicParams = false;
+export const dynamicParams = !IS_EXPORT;
 
 export function generateStaticParams() {
-  return generateBlogStaticParams('en');
+  return IS_EXPORT ? generateBlogStaticParams('en') : [];
 }
 
 export async function GET(
   _request: Request,
   { params }: { params: { slug: string[] } },
 ) {
   const slugPath = params.slug.join('/');
-  const { post } = await getBlogPost('en', slugPath);
+  // Tina's client defaults to errorPolicy: 'throw', so an unknown slug throws
+  // rather than returning { post: null } (same convention as app/blog/[...slug]).
+  let post: Awaited<ReturnType<typeof getBlogPost>>['post'];
+  try {
+    ({ post } = await getBlogPost('en', slugPath));
+  } catch (error) {
+    console.error(
+      `Error fetching post for Instagram image: ${slugPath}`,
+      error,
+    );
+    post = null;
+  }
+  if (!post) {
+    // Unknown slug: 404 rather than render + ISR-cache a generic fallback image.
+    return new Response(null, { status: 404 });
+  }
   return renderBlogInstagramImage({
-    title: post?.title ?? 'TinaCMS Blog',
-    author: post?.author,
+    title: post.title,
+    author: post.author,
     seed: slugPath,
   });
 }

app/blog/og/[...slug]/route.tsx

@@ -6,29 +6,47 @@
 // So we serve the image from a distinct prefix (/blog/og/<slug>) and point
 // `openGraph.images` at it from the post's generateMetadata.
 //
-// force-static + generateStaticParams pre-renders one image per post at build
-// (where the fonts/photos under public/ are readable via fs).
+// Rendered on-demand and cached (ISR): the first request for a post's image
+// renders it, then it's served from cache. A static export (output: 'export')
+// can't generate on-demand, so it must prebuild every image instead — gated on
+// the same EXPORT_MODE switch next.config.js uses. Fonts/photos load from
+// public/ on disk with a live production-host fallback (see utils/og/ogAssets),
+// so they resolve at build and at on-demand runtime.
 
 import { generateBlogStaticParams } from 'utils/blog/generateBlogStaticParams';
 import { getBlogPost } from 'utils/blog/getBlogPost';
 import { renderBlogOgImage } from 'utils/og/blogOgImage';
 
+const IS_EXPORT = process.env.EXPORT_MODE === 'static';
+
 export const dynamic = 'force-static';
-export const dynamicParams = false;
+export const dynamicParams = !IS_EXPORT;
 
 export function generateStaticParams() {
-  return generateBlogStaticParams('en');
+  return IS_EXPORT ? generateBlogStaticParams('en') : [];
 }
 
 export async function GET(
   _request: Request,
   { params }: { params: { slug: string[] } },
 ) {
   const slugPath = params.slug.join('/');
-  const { post } = await getBlogPost('en', slugPath);
+  // Tina's client defaults to errorPolicy: 'throw', so an unknown slug throws
+  // rather than returning { post: null } (same convention as app/blog/[...slug]).
+  let post: Awaited<ReturnType<typeof getBlogPost>>['post'];
+  try {
+    ({ post } = await getBlogPost('en', slugPath));
+  } catch (error) {
+    console.error(`Error fetching post for OG image: ${slugPath}`, error);
+    post = null;
+  }
+  if (!post) {
+    // Unknown slug: 404 rather than render + ISR-cache a generic fallback image.
+    return new Response(null, { status: 404 });
+  }
   return renderBlogOgImage({
-    title: post?.title ?? 'TinaCMS Blog',
-    author: post?.author,
+    title: post.title,
+    author: post.author,
     seed: slugPath,
   });
 }

app/zh/blog/instagram/[...slug]/route.tsx

@@ -2,22 +2,39 @@ import { generateBlogStaticParams } from 'utils/blog/generateBlogStaticParams';
 import { getBlogPost } from 'utils/blog/getBlogPost';
 import { renderBlogInstagramImage } from 'utils/og/blogInstagramImage';
 
+const IS_EXPORT = process.env.EXPORT_MODE === 'static';
+
 export const dynamic = 'force-static';
-export const dynamicParams = false;
+export const dynamicParams = !IS_EXPORT;
 
 export function generateStaticParams() {
-  return generateBlogStaticParams('zh');
+  return IS_EXPORT ? generateBlogStaticParams('zh') : [];
 }
 
 export async function GET(
   _request: Request,
   { params }: { params: { slug: string[] } },
 ) {
   const slugPath = params.slug.join('/');
-  const { post } = await getBlogPost('zh', slugPath);
+  // Tina's client defaults to errorPolicy: 'throw', so an unknown slug throws
+  // rather than returning { post: null } (same convention as app/blog/[...slug]).
+  let post: Awaited<ReturnType<typeof getBlogPost>>['post'];
+  try {
+    ({ post } = await getBlogPost('zh', slugPath));
+  } catch (error) {
+    console.error(
+      `Error fetching post for Instagram image: ${slugPath}`,
+      error,
+    );
+    post = null;
+  }
+  if (!post) {
+    // Unknown slug: 404 rather than render + ISR-cache a generic fallback image.
+    return new Response(null, { status: 404 });
+  }
   return renderBlogInstagramImage({
-    title: post?.title ?? 'TinaCMS Blog',
-    author: post?.author,
+    title: post.title,
+    author: post.author,
     seed: slugPath,
   });
 }

app/zh/blog/og/[...slug]/route.tsx

@@ -5,22 +5,36 @@ import { generateBlogStaticParams } from 'utils/blog/generateBlogStaticParams';
 import { getBlogPost } from 'utils/blog/getBlogPost';
 import { renderBlogOgImage } from 'utils/og/blogOgImage';
 
+const IS_EXPORT = process.env.EXPORT_MODE === 'static';
+
 export const dynamic = 'force-static';
-export const dynamicParams = false;
+export const dynamicParams = !IS_EXPORT;
 
 export function generateStaticParams() {
-  return generateBlogStaticParams('zh');
+  return IS_EXPORT ? generateBlogStaticParams('zh') : [];
 }
 
 export async function GET(
   _request: Request,
   { params }: { params: { slug: string[] } },
 ) {
   const slugPath = params.slug.join('/');
-  const { post } = await getBlogPost('zh', slugPath);
+  // Tina's client defaults to errorPolicy: 'throw', so an unknown slug throws
+  // rather than returning { post: null } (same convention as app/blog/[...slug]).
+  let post: Awaited<ReturnType<typeof getBlogPost>>['post'];
+  try {
+    ({ post } = await getBlogPost('zh', slugPath));
+  } catch (error) {
+    console.error(`Error fetching post for OG image: ${slugPath}`, error);
+    post = null;
+  }
+  if (!post) {
+    // Unknown slug: 404 rather than render + ISR-cache a generic fallback image.
+    return new Response(null, { status: 404 });
+  }
   return renderBlogOgImage({
-    title: post?.title ?? 'TinaCMS Blog',
-    author: post?.author,
+    title: post.title,
+    author: post.author,
     seed: slugPath,
   });
 }

utils/og/blogInstagramImage.tsx

@@ -44,12 +44,12 @@ export async function renderBlogInstagramImage({
   seed,
 }: BlogInstagramInput): Promise<ImageResponse> {
   const mappedAvatar = authorImagePath(author);
-  const avatarUri = mappedAvatar ? pngDataUri(mappedAvatar) : null;
+  const avatarUri = mappedAvatar ? await pngDataUri(mappedAvatar) : null;
   const llamaSrc = pickLlama(seed);
-  const llamaUri = avatarUri ? null : pngDataUri(llamaSrc);
+  const llamaUri = avatarUri ? null : await pngDataUri(llamaSrc);
   const llamaWidth = LLAMA_WIDTH[llamaSrc];
 
-  const logo = logoDataUri();
+  const logo = await logoDataUri();
   const displayTitle = truncateTitle(title.trim() || 'TinaCMS Blog', TITLE_CAP);
   const fontSize = pickFontSize(
     displayTitle.length,
@@ -203,7 +203,7 @@ export async function renderBlogInstagramImage({
     </div>,
     {
       ...IG_SIZE,
-      fonts: ogFonts(),
+      fonts: await ogFonts(),
     },
   );
 }

utils/og/blogOgImage.tsx

@@ -54,12 +54,12 @@ export async function renderBlogOgImage({
   seed,
 }: BlogOgInput): Promise<ImageResponse> {
   const mappedAvatar = authorImagePath(author);
-  const avatarUri = mappedAvatar ? pngDataUri(mappedAvatar) : null;
+  const avatarUri = mappedAvatar ? await pngDataUri(mappedAvatar) : null;
   const llamaSrc = pickLlama(seed);
-  const llamaUri = avatarUri ? null : pngDataUri(llamaSrc);
+  const llamaUri = avatarUri ? null : await pngDataUri(llamaSrc);
   const llamaLayout = LLAMA_LAYOUT[llamaSrc];
 
-  const logo = logoDataUri();
+  const logo = await logoDataUri();
   const displayTitle = truncateTitle(title, TITLE_CAP);
   const fontSize = pickFontSize(
     displayTitle.length,
@@ -243,7 +243,7 @@ export async function renderBlogOgImage({
     </div>,
     {
       ...OG_SIZE,
-      fonts: ogFonts(),
+      fonts: await ogFonts(),
     },
   );
 }

utils/og/ogAssets.test.ts

@@ -0,0 +1,63 @@
+// Covers the fail-loud asset loading. A genuinely-absent optional asset (404)
+// resolves to null so the caller can fall back (llama), while a transient load
+// failure (any non-404 / network error) rejects — so the render 500s and isn't
+// ISR-cached, instead of silently shipping a degraded image that sticks for the
+// life of the deployment. The module memoizes at module scope and derives its
+// fetch origin from env at import, so each case runs in an isolated registry.
+//
+// Paths under /__missing__ don't exist in public/ on disk, so loadPublic falls
+// through to the (mocked) origin fetch — no fs mock needed.
+
+function loadOgAssets() {
+  // jest 25 doesn't recognise `node:`-prefixed builtins as core modules, so the
+  // real fs/path can't resolve under test. doMock both (non-hoisted, so ts-jest
+  // 25 doesn't choke on the hoist transform) before the module loads, so
+  // readFileSync always misses and every load goes through the origin fetch.
+  jest.doMock('node:fs', () => ({
+    readFileSync: () => {
+      throw new Error('ENOENT');
+    },
+  }));
+  jest.doMock('node:path', () => ({ join: (...p: string[]) => p.join('/') }));
+  // Set the production alias so the origin-fetch fallback is enabled.
+  process.env.VERCEL_PROJECT_PRODUCTION_URL = 'tina.io';
+  let mod: typeof import('./ogAssets');
+  jest.isolateModules(() => {
+    mod = require('./ogAssets');
+  });
+  return mod;
+}
+
+// AbortSignal.timeout exists on the Vercel runtime (Node 20+) but not jest 25's
+// env; the mocked fetch ignores the signal anyway, so a no-op stub is enough.
+beforeAll(() => {
+  if (typeof AbortSignal.timeout !== 'function') {
+    (AbortSignal as unknown as { timeout: () => AbortSignal }).timeout = () =>
+      new AbortController().signal;
+  }
+});
+
+afterEach(() => {
+  jest.resetModules();
+  global.fetch = undefined as unknown as typeof fetch;
+});
+
+describe('asset loading fail-loud semantics', () => {
+  it('resolves null for a genuinely-absent asset (404) so the caller can fall back', async () => {
+    global.fetch = jest.fn(
+      async () => ({ ok: false, status: 404 }) as Response,
+    );
+    const { pngDataUri } = loadOgAssets();
+    await expect(pngDataUri('/__missing__/nobody.png')).resolves.toBeNull();
+  });
+
+  it('rejects on a transient (non-404) fetch failure rather than degrading silently', async () => {
+    global.fetch = jest.fn(
+      async () => ({ ok: false, status: 503 }) as Response,
+    );
+    const { pngDataUri } = loadOgAssets();
+    await expect(pngDataUri('/__missing__/blip.png')).rejects.toThrow(
+      /asset fetch failed/i,
+    );
+  });
+});