Blog Post Rendering Strategy

Every blog has to answer the same question: how does a post get from the database onto the reader's screen? For the past two years my site went with the laziest answer available: pure CSR. This post is the story of rewriting that answer three times: first moving to SSG, then getting slapped in the face by my own prerender and switching to ISR, and finally spending an entire night wrestling with render timing just so that opening a post wouldn't flash.

Let me get a few terms straight first, because the whole post revolves around them:

• SSR (server-side rendering): the server renders the HTML fresh on every request and sends it out, so the first paint already has content.
• SSG (static site generation): pages are pre-rendered into static HTML files at build time and simply served as files afterwards.
• CSR (client-side rendering): the browser gets an empty shell and paints it itself — which is exactly what I had.
• ISR (incremental static regeneration): in between the two — serve the pre-generated static HTML first (fast), and regenerate it in the background on a schedule or on demand (fresh).

I've tried to present the whole process faithfully, including the places where I judged wrong and the places where I had to stop myself and think again.

Background: a blog invisible to crawlers, and a me who wanted everything in Rust#

Before the rewrite, this site was a perfectly ordinary React 19 SPA: BrowserRouter + <Routes>, native fetch plus a hand-rolled cache, zero SSR, one hundred percent CSR. A real person opening the homepage got an empty root node plus a bundle of JS, with all the content grown by the browser; crawlers could see meta tags only because the serve layer used user-agent detection to spot bots and stuffed <title>, OG and JSON-LD into the static HTML. In other words: the body of a post had never once been rendered by the server. For a blog where the content is the whole product, that architecture is backwards.

At the same time I had something else on my mind: I wanted to move the entire backend to Rust. That one needs some setup for readers without the context, because it actually has nothing to do with making the blog faster.

Incidentally, the SEO symptom I cared most about back then was that Google kept autocorrecting "Koimsurai" into "Katsurai" (a tonkatsu place in Kyoto). Digging into it, that turned out to be a brand entity recognition problem, and SSG can't fix it. But "both humans and crawlers should get body content that was actually rendered" was still worth doing.

Picking a stack: SSR / SSG / CSR, and why not Next#

Laid out flat there were three roads: keep the status quo (all CSR plus the bot meta shim), a hybrid SSG (prerender the article pages, leave the dashboards on CSR), or SSR for the whole site. For a blog the answer leans surprisingly toward SSG — and it actually fits my definition of "all Rust" better:

• what SSG produces is just a pile of static HTML that the Rust backend can serve directly, meaning zero rendering Node in production;
• full-site SSR would add a long-lived Node render process in prod, which dilutes "all Rust" instead;
• and my site naturally splits into two kinds of content: semi-static posts and static pages (which need SEO) and live dashboards (now / watching / music — constantly changing, and they need no SEO at all). Which lines up perfectly: article bodies go SSG, dashboards stay CSR.

So what about Next.js? I did have the migration from React evaluated, but in the end I didn't pick it. My grudge against Next had already been accumulating on other projects: a Tauri desktop app built on Next whose builds were so slow I couldn't stand it; the NAS frontend was worse — it got compromised through an RCE hole in Next 16.0.6 and had a crypto miner planted in it.

The evaluation put it behind TanStack Start, so the framework shortlist collapsed to TanStack Start vs React Router 7 framework mode. As for Next's signature RSC, it is useless here: all my data lives in the Rust backend, so a server component would at best await fetch(rustApi) — the RSC benefit cancels straight out.

What really tipped the scales toward TanStack Start was one single thing:

Worth noting how new all of this is: TanStack Start v1.0 only shipped in March 2026, Vite is on 8.x (with Rolldown underneath), and the server engine below it, Nitro, is still on a v3 beta (TanStack Start integrates it directly). The whole stack is bleeding edge. As you'll see later, that newness was both the fun part and something that bit me several times.

What about Astro, which ships even less JS? It got skipped in round one because I have heavy interactive things like three.js and Monaco (React-first is the realistic call); later, chasing "drop the eval and turn CSP on", I evaluated it seriously one more time, and I'll get to that conclusion below. The final mental model is blunt: "an SSG/ISR first paint plus SPA-style navigation afterwards". The initial load is HTML the server pre-generated (the source of the SEO and first-paint dividend), and after hydrate in-site page switches still feel like an SPA. You get both halves.

Implementation: bake the body into the HTML, keep heavy interactivity on the client#

A PoC first: run the prerender against a real post and confirm that the body really is baked into the HTML. /blog/39/index.html came out at 38KB, with a complete <article>, headings and tables inside the body. Four out of four green. The core conclusion in one line: prerender the body, leave heavy interactivity on CSR. When I built it for real, the render pipeline looked like this:

Two key decisions. The first is letting the API list which pages to prerender: instead of hard-coding five /en/blog/:id routes, one dynamic route $locale/blog/$id handles every language; at build time it hits /api/posts for each post's available_locales and only generates the languages that actually exist, with hreflang generated from the same source, never faked.

The second is baking the body into the HTML and keeping the heavy interactivity on the client: that eighteen-hundred-line interactive BlogPost, the one that pulls in mermaid and shiki, goes through lazy + ClientOnly, which guarantees that things that explode inside Node — three.js, mermaid — never enter the server bundle.

This road came with a string of server-bundle and hydration potholes. A few representative ones:

• LinkCard dragged the entire BlogPost down with it. Two pages, History and AboutSite, did import { LinkCard } from './BlogPost' — LinkCard itself is perfectly SSR-able (it is a link preview card, it never touches window), but it was locked inside that two-thousand-line file together with mermaid, so a single import dragged the whole mermaid bundle into the server bundle. The fix was extracting LinkCard into its own SSR-safe module, decoupled from mermaid.
• The nav bar speaking Korean: #418 hydration mismatch. The site-wide shell (Header/Footer) hangs off __root but sits outside each page's LocaleProvider, so the shell's translations fell back to the global i18next instance. Prerendering several pages together leaked languages between them: the SSR HTML said <html lang=en> and the hero was English (correct), while the nav bar was Korean. Nav bar ko on the server, nav bar en on the client → #418. The fix: wrap a provider at the root that derives the language from the URL, so the shell gets the right locale too.
• The old service worker refusing to die. The old SPA had a PWA plugin registering a SW that precached the old assets; the new architecture has none. Returning visitors got the old shell plus the new HTML → broken styles plus #418. The fix: have the serve layer ship a self-terminating /sw.js (unregister, clear caches, reload).

A few finer potholes on the render path are worth recording too, because every one of them comes back to "SSR and the client have to match character for character":

• A colon in the title auto-splits main title from subtitle. The schema has no subtitle field, so a splitTitle on the frontend cuts at the first colon: the main title goes into h1, the subtitle into p. Purely presentational — document.title and og:title still use the full title, so SEO is unaffected.
• Footnote ids hijacked the scroll-spy. The scroll-spy originally tracked "every element on the page that has an id", and the user-content-fn-… ids from footnotes and alerts stole the active state, so the TOC highlight simply vanished. The fix: only look at the set of heading ids the TOC actually lists. I also added scroll-margin-top to the anchors so headings don't end up buried under the sticky header after a jump.
• mermaid's ELK layout crashes with circular JSON on an SSR site. Switching to the Adaptive (ELK) layout threw Converting circular structure to JSON outright. Digging to the bottom: @mermaid-js/layout-elk runs JSON.stringify over the entire ELK graph, and this site's <html> is rendered by React through TanStack Start, so documentElement carries a __reactFiber property — serializing it walks straight into a circular reference. This is a pothole specific to React SSR sites. The fix is a reference-counted guard that temporarily swaps JSON.stringify for a version that skips DOM nodes while a render is in flight.

The prerender produced 111 files, and not one of them was ever served#

Halfway through the implementation I ran into an absurd discovery. The prerender inside the docker build ran fast and clean (7.8 seconds, 111 files, zero errors), and .output/public/blog/index.html really was written out — but actually requesting /blog/index.html always came back 404, and hitting /en twice in a row gave two different md5s. Which means: every single request was re-running SSR, and not one of those 111 files had ever been served. The root cause is that Nitro's list of registered static assets is scanned before the prerender writes its files. Generating a pile of files nobody serves is pure wasted build time — and it forced the build to reach out to the live site for the post list.

So I ripped the prerender out entirely and went pure ISR. A quick primer on the machinery of ISR is in order here, because the official route doesn't work on my setup:

What saves it is Nitro's node-server preset: it has SWR built in, one line of routeRules does the job, and the background regeneration happens inside my own server:

// vite.config.start.ts —— ISR in one line, instead of 100 lines I write myself
const ISR_ROUTE_RULES = {
  ...swrRules(ISR_PAGES.flatMap(localeVariants), 3600),        // UI pages: 1 hour
  ...swrRules(localeVariants('blog'), 300),                    // list page: new posts should show up soon → 5 minutes
  ...swrRules(localeVariants('blog').map((p) => `${p}/**`), 3600), // post pages: content barely changes → 1 hour
};

The site's whole request flow now looks like this — Rust is the only real backend, and Node/Nitro is just a rendering shell (which is exactly my "all business logic in Rust, the Node layer in front only renders" definition landing in practice):

Three potholes in this stretch are worth unpacking:

The list page cached an empty shell. The ISR-cached /blog was empty at first, because the Blog component fetched its data inside useEffect, and useEffect does not run on the server → SSR emitted nothing but a loading skeleton (prerender wouldn't have saved it either; it doesn't run useEffect any more than SSR does). The fix was moving the fetch into the route loader and feeding the initial data in through useLoaderData: /blog's SSR output went from a 19,541-byte shell to 74,242 bytes, complete with titles and 8 post links.

Publish and it refreshes: on-demand regeneration. A TTL alone isn't enough; a new post needs to be visible to crawlers immediately. The approach is a Nitro server route /_revalidate (protected by a header secret; deliberately not under /api/*, because nginx sends everything under /api/ to Rust, so the frontend would never receive it), which the Rust backend hits fire-and-forget after a successful publish or edit to purge the cache. And I built it as an axum middleware rather than wiring it into 14 write endpoints one at a time. Wiring them one at a time guarantees you miss one, and a miss doesn't error — it just quietly stops updating.

Cache rules use an allowlist, not /**. Wrapping the whole site (/**) is fail-open: any page added later that reads cookies or renders user data would be publicly cached by default, and nobody would notice. An allowlist is the opposite — a new page isn't cached unless you say so. Explicitly not cached: / (it reads cookies and Accept-Language to do language routing, so caching it means handing the first visitor's language to the whole world), /admin and /auth.

MDX: a pipeline that evals, and a debt I want to repay#

Up to this point posts were still rendered with react-markdown. Then I wanted custom blocks like <Note>, <Annot>, <Diff> and <Chart> (to make the reading experience immersive enough), so I layered on an MDX pipeline (opt-in per post; only posts with format=mdx go through it). This pipeline is the most technical stretch of the post, and my own understanding of it needed correcting right from the start:

Compilation happens on the server only. @mdx-js/mdx's compiler is micromark + acorn, which is heavy and has no business in the client bundle. So I use TanStack's createServerFn: during SSR it runs in-process, and on client-side navigation it makes an RPC back to the server for the compiled result, producing a function-body string (serializable, dehydratable into the HTML). Execution happens on the client: the frontend takes that string and runs it into a React component with runSync — and runSync is new Function underneath, which is client-side eval.

// server-only: the compiler is heavy and stays out of the client bundle; the function-body string it emits is serializable
export const compileMdx = createServerFn({ method: 'POST' })
  .handler(async ({ data: source }) => {
    const { compile } = await import('@mdx-js/mdx');
    return String(await compile(source, { outputFormat: 'function-body', remarkPlugins: [remarkGfm, remarkAlert] }));
  });

// client: runSync synchronously turns it into a component (works in SSR and hydration); ⚠️ new Function underneath = eval
const { default: Content } = runSync(compiled, jsxRuntime);

A word about the editor detour along the way: I did once install MDXEditor (the only MDX-native WYSIWYG editor on the market) as a spike, but it has 131 dependencies and rendered all my custom blocks as a generic row of "gear icon + label" UI rather than the real components — and I prefer the way Monaco looks anyway. Then it clicked: MDXEditor was never a prerequisite for making MDX work. I write MDX source in Monaco and the renderer (compileMdx + runSync) paints it out; that is enough. The whole spike was backed out cleanly and Monaco stayed. A few other decisions: MDX falls back to markdown automatically when compilation fails (one fat-fingered tag shouldn't blow up an entire post); MDX posts and markdown posts share the same set of base components (shiki highlighting, mermaid, link cards, heading anchors).

That debt I want to repay sits right on this runSync:

So how do I get rid of this eval? My first idea was islands: rewrite every interactive block as "CSS plus one bundled piece of vanilla JS", and mount the heavy ones through a registry. But that means rewriting a great deal, with behavioural regression risk. Then a far cleaner path clicked. The eval exists only because I compile MDX into function-body (a format that can only run through new Function). If I compile into a real ES module instead, the client can load it with import() — and a same-origin import() is allowed under a strict CSP script-src 'self' (that is module loading, not eval). The entire pipeline, every block and every animation stays untouched: zero rewrites, zero regressions. Islands are just the fallback if this one hits a wall. The target flow looks like this:

(This one hasn't been started; it is filed in the backlog. For the same goal I went back and evaluated Astro seriously: it is islands-native and naturally CSP-friendly, but Astro is a standalone framework with its own build, and it cannot be embedded into my existing TanStack Start. "Use Astro for the blog only" in practice means splitting the site into two apps: the shared header, TOC, reactions and comments would all have to be rewritten as islands, and i18n, ISR, SEO and the Rust data layer would all have to be rebuilt. That is a sledgehammer for a nut, and you have to demolish the kitchen to swing it. The dynamic-import route is worth vastly more per unit of effort.)

No more flash on the first frame: the long march of entry-render debugging#

All of the above shipped, but what really kept me grinding into the small hours was "the instant you enter a post". This whole section is render-timing potholes, and it is the heart of the post. Results first. On the left is how bad it was at the time; on the right is after the cleanup:

Writing all this made me curious where everybody else's content site ended up landing:

Wrapping up: the ledger of three rewrites#

This render long march really breaks down into three ledgers at three different levels:

1. SEO and the first paint are the dividend of SSG/ISR; hydration is the whole new class of bug you buy with it. From here on, article bodies, titles and hreflang really are rendered into the HTML, and crawlers see them without running JS; the price is one more Node render shell, plus a kind of bug that didn't exist before: "what the server sends and what the client paints must match character for character".
2. Measure, don't guess. The single most valuable thing that night was forcing myself to stop and ask "is this really fixed, or did I just route around it / guess right?". It pushed back two diagnoses I had made on impressions (the fake fixes for those three bugs, and the scroll serialization bug), and made me measure the truth out with ablation tests and Playwright.
3. A few rules that will bite you over and over: useEffect does not run on the server, so any page that fetches inside it will only ever emit an empty shell from both SSR and prerender; a fail-open site-wide cache rule is a security landmine; and if you purge caches by path prefix, remember to exclude the high-frequency endpoints.

There are a few debts still outstanding, listed honestly: MDX's runSync is a client-side eval — harmless for the moment, given that CSP isn't even switched on yet, but it is the thing I want gone before I go to a strict CSP. The plan is to compile MDX into an ESM module and replace runSync with import() (islands are only the fallback); the ISR cache still lives in memory, so every deploy or restart zeroes the whole site (no fs driver wired up yet); and the old SEOHead (react-helmet) hasn't fully retired either. Rendering is probably a question you never finish answering, but at least now, for every step a post takes from the database to your screen, I know why it looks the way it does.