Support prerendering non-HTML responses (e.g. Open Graph images)

[u-42]

Hi! 👋

I'm using TanStack Start with Fumadocs and would like to prerender og:image.

My first attempt was to add a hidden <a herf="/api/og/key" /> to the page route so the prerenderer scrawler would generate it, but I realized it only processes text/html responses.

I also considered generating the images from onSuccess hook, but it doesn't seem like a great fit with the Fumadocs vite plugin and i don't have access to the prerender server either.

Would supporting non-HTML responses (e.g. image/png) be within the scope of the prerender plugin? Since these routes are deterministic, it seems like they could be generated alongside HTML pages.

I'm happy to help implement this once there's agreement on the design.

[u-42]

Alternative Approach for OG Image Prerendering in FurmaDocs

1. Manual Path Discovery
   Parse the content folder to identify documentation pages. Derive OG image paths for each page.

2. Configuration with createOgPrerenderPages
   Convert paths into prerender configuration objects. Disable crawlLinks and inject the x-og-prerender: base64 header.

3. Header-Based Encoding Strategy
   In the OG handler, check for the x-og-prerender: base64 header. Convert the ImageResponse buffer to a base64-encoded string if the header is set.

4. Binary Persistence via onSuccess Hook
   Decode base64 string back to binary buffer. Write binary buffer to the filesystem as a PNG file.

The inconvenients of this approach are:

• Inability to Use Crawling for OG Generation: The system does not support automatic link crawling for generating Open Graph (OG) images. Instead, it requires explicit path discovery.

• Double Transformation: To accommodate the text-oriented prerender system, the approach involves a double transformation process. First, binary image data is encoded to a base64 string. Then, the base64 string is decoded back to binary image data for persistence on the filesystem. This double transformation adds complexity to the process.

source: https://github.com/rixlhq/docs/tree/main

[mburumaxwell]

Hit this on a marketing site (Start prerender + fumadocs, images rendered with takumi). Sharing a finding in case it is useful.

The limitation comes down to one line in prerender.js:

const html = await res.text();
const filepath = path.join(outputDir, filename);
await promises.mkdir(path.dirname(filepath), { recursive: true });
await promises.writeFile(filepath, html);

res.text() is a UTF-8 decode, so a PNG's leading 0x89 is not valid on its own, becomes U+FFFD, and lands on disk as ef bf bd 50 4e 47. WebP fares no better: the RIFF header survives, the compressed payload after it does not. The build passes either way, which is the awkward part. You get a corrupt file rather than a missing one, so nothing fails until a social preview does.

Nitro handles this without branching on content type. It buffers unconditionally and exposes the text lazily, so the link crawler and any consumer of the string are unaffected (prerender.ts):

let dataBuff: Buffer | undefined = Buffer.from(await res.arrayBuffer());

Object.defineProperty(_route, "contents", {
  get: () => (dataBuff ? dataBuff.toString("utf8") : undefined),
  set(value: string) { if (dataBuff) dataBuff = Buffer.from(value); },
});
...
await writeFile(filePath, dataBuff!);

Applied here that would be roughly: buffer the response, keep passing dataBuff.toString('utf8') to onSuccess and extractLinks exactly as today, and write the buffer instead of the string. HTML behaviour is unchanged.

Discovery seems worth treating as a separate problem. extractLinks only matches <a href>, so an og:image in a <meta> tag is never crawled and the paths have to be supplied whichever way the bytes are written. I handle that outside the prerender at the moment, by deriving the image paths from the sitemap the prerender has just written, which keeps them from drifting away from the pages that reference them.