ブログ記事のレンダリング戦略

どのブログも、結局は同じ問いに答えることになります。1 本の記事は、どうやってデータベースから読者の画面までたどり着くのか?このサイトはこの 2 年、いちばん横着な答えを使っていました。純 CSR です。この記事は、その答えを3 回書き直した記録です。まず SSG に移し、次に自分の prerender に裏切られて ISR へ切り替え、最後は「記事に入った瞬間にチラつかせない」ためにレンダリングの時系列と一晩じゅう格闘しました。

先に用語を整理しておきます。この記事は最初から最後までこの 4 つを軸に回ります。

• SSR(サーバーサイドレンダリング):リクエストのたびにサーバーがその場で HTML をレンダリングして返す方式。初期表示から中身がある。
• SSG(静的サイト生成):build 時にページを静的な HTML ファイルとして事前レンダリングしておき、以降はそのファイルをそのまま返す。
• CSR(クライアントサイドレンダリング):ブラウザが空からの殻からを受け取って自分で描く。つまり私が元々使っていた方式。
• ISR(増分静的再生成):両者の中間。まず事前生成した静的 HTML を返し(速い)、バックグラウンドで定期的に、あるいはトリガー時に再生成する(新しい)。

判断を誤ったところも、自分で自分を止めて考え直したところも含めて、できるだけ忠実ちゅうじつに過程を残します。

背景:クローラーには透明なブログと、全部 Rust にしたかった私#

改修前、このサイトはごく普通の React 19 SPA でした。BrowserRouter + <Routes>、native fetch + 手書きキャッシュ、SSR の使用量は 0、100% CSR。人間がトップページを開いて受け取るのは空のルートノードと JS の塊だけで、中身はすべてブラウザが生やします。それでもクローラーが meta を見られたのは、serve 層が user-agent で bot を判定し、<title> や OG、JSON-LD を静的 HTML に押し込んでいたからです。言い換えると、記事の body は、一度もサーバーでレンダリングされたことがなかったわけです。「中身がすべて」のブログにとって、この構成は逆さまでした。

同じ時期、頭の中にはもう 1 つ別のことがありました。バックエンドを全部 Rust にしたい。 これは背景を知らない読者のために少し前置きが要ります。というのも、これは「ブログを速くする」こととは何の関係もないからです。

ついでに書いておくと、当時いちばん気にしていた SEO の症状は、Google が「Koimsurai」を「Katsurai」(京都のとんかつ屋)に自動修正してくることでした。調べてみるとそれはブランドのエンティティ認識の問題で、SSG では直りません。とはいえ「人間もクローラーも、ちゃんと render された本文を受け取るべきだ」という一点は、それでもやる価値がありました。

技術選定:SSR / SSG / CSR、そしてなぜ Next ではなかったか#

並べてみると道は 3 本です。現状維持(全 CSR + bot 向け meta shim)、ハイブリッド SSG(本文ページは prerender、ダッシュボードは CSR のまま)、あるいはサイト全体 SSR。ブログにとっての答えは意外にも SSG 寄りで、しかも私の言う「全 Rust」の定義にむしろよく噛み合っていました。

• SSG の成果物は静的 HTML の束なので、Rust バックエンドがそのまま serve すればいい。production にレンダリング用の Node はゼロ。
• サイト全体 SSR にすると prod に常駐の Node レンダリングプロセスが 1 つ増え、かえって「全 Rust」が薄まる。
• そしてこのサイトは、そもそもコンテンツが 2 種類に分かれます。半静的な記事/静的ページ(SEO が要る)と、リアルタイムのダッシュボード(now / 視聴 / 音楽。ずっと変わり続けるし SEO はそもそも不要)。ちょうどいい。本文は SSG、ダッシュボードは CSR のまま。

では Next.js は?サイトを React から移行する案も人に評価してもらいましたが、最終的には選びませんでした。Next への恨みは、実は別のプロジェクトでとっくに溜まっていました。Next を使った Tauri のデスクトップアプリはビルドが我慢できないほど遅かったし、NAS のフロントエンドはもっと悲惨で、Next 16.0.6 の RCE 脆弱性を突かれて侵入され、マイニングプログラムを仕込まれました。

評価した結果 Next は TanStack Start に勝てず、フレームワークの最終候補は TanStack Start vs React Router 7 framework mode に収束しました。Next の看板である RSC も、私のところでは出番がありません。データはすべて Rust バックエンドにあるので、server component にできるのはせいぜい await fetch(rustApi) で、RSC の利点はそこで相殺されてしまいます。

天秤を本当に TanStack Start 側に傾けたのは、たった 1 つのことでした。

ついでに、このスタックがどれだけ新しいかも書いておきます。TanStack Start v1.0 は 2026 年 3 月に出たばかり、Vite は 8.x(内部は Rolldown に置き換わった)、その下のサーバーエンジンである Nitro に至ってはまだ v3 の beta(TanStack Start がそれを直接統合しています)。まるごと bleeding edge です。後で見ていくとおり、この「新しさ」は楽しみでもあり、何度も私に噛みついてもきました。

では、もっと JS を節約できる Astro は?第 1 ラウンドでは three.js や Monaco のような重い interactive があるので見送りました(React-first のほうが現実に合う)。その後「eval を外して CSP を有効にする」ために、もう一度真剣に評価しています。結論は後述します。最終的なメンタルモデルはとてもすっきりしていました。「SSG/ISR による初期表示 + SPA 的なその後の遷移」。初回ロードはサーバーが事前生成した HTML(SEO と初期表示のボーナスはここから来る)、hydrate したあとはサイト内のページ切り替えが SPA のように動く。両方のおいしいところを取ります。

実装:本文を HTML に焼き込み、重い interactive は client に残す#

まず PoC で検証。実際の記事で prerender を走らせ、本文が HTML に焼き込まれていることを確認しました。/blog/39/index.html は 38KB、body には完全な <article>、見出し、テーブルが入っています。4 項目すべてグリーン。核心の結論は一言で、本文は prerender、重い interactive は CSR のまま。 本実装のレンダリングパイプラインはこうなりました。

重要な決定が 2 つ。1 つめは、どのページを prerender するかを API から列挙することです。/en/blog/:id を 5 本ベタ書きするのではなく、$locale/blog/$id という 1 本の動的ルートで全言語を処理します。build 時に /api/posts を叩いて各記事の available_locales を取得し、実在する言語だけを生成。hreflang もこれに従って出力し、決して捏造しません。

2 つめは、本文を HTML に焼き込み、重い interactive は client に残すことです。1800 行あって mermaid や shiki を引き込む interactive 版の BlogPost は lazy + ClientOnly にして、three.js や mermaid のような Node の中で爆発するものがサーバー側のバンドル(server bundle)に決して入らないことを保証しました。

この道では server bundle と hydration の落とし穴あなを一通ひととおり踏みました。代表的なものをいくつか。

• LinkCard が BlogPost 丸ごとを道連れにした。 History と AboutSite の 2 ページが import { LinkCard } from './BlogPost' していました。LinkCard 自体は完全に SSR できます(リンクプレビューカードで window には触らない)。しかし mermaid と一緒にあの 2000 行のファイルに閉じ込められているので、import した瞬間に mermaid 一式が server bundle に引きずり込まれます。解決策は、LinkCard を独立した SSR-safe なモジュールに切り出して mermaid と切り離すこと。
• ナビゲーションバーが韓国語をしゃべる #418 hydration mismatch。 サイト全体の外殻(Header/Footer)は __root にぶら下がっているのに、各ページの LocaleProvider の外側にありました。そのため外殻の翻訳がグローバルな i18next インスタンスにフォールバックします。複数ページをまとめて prerender すると言語が漏れて、SSR HTML は <html lang=en>、Hero は英語(正しい)なのに、ナビゲーションバーだけ韓国語。SSR のナビは ko、client のナビは en → #418 です。解決策は、root に URL から言語を判定する provider をもう 1 層かぶせて、外殻にも正しいロケールを渡すこと。
• 古い Service Worker の亡霊。 旧 SPA には PWA plugin が登録した、古いアセットを precache する SW がありました。新しい構成にはそれがありません。再訪者は古い外殻 + 新しい HTML を受け取り → スタイル崩壊 + #418。解決策は、serve 層から自害する /sw.js(登録解除 + キャッシュ削除 + reload)を配ること。

レンダリング経路上の細かい穴もいくつか、ついでに記録しておきます。どれも「SSR と client は一字一句一致していなければならない」に関係するからです。

• タイトルのコロンで主題と副題を自動分割。 schema に副題のカラムがないので、フロントエンドの splitTitle が最初のコロンで切り、主題は h1、副題は p に入れます。純粋な表示層の処理で、document.title と og:title は完全なタイトルのままなので SEO に影響はありません。
• scroll-spy が脚注の id に乗っ取られた。 scroll-spy は元々「ページ上の id を持つ全要素」を追跡していたため、脚注や alert の user-content-fn-… という id が active 状態を奪い、目次のハイライトが消えてしまいました。解決策は「目次に実際に載っている見出しの id 集合」だけを見ること。アンカーには scroll-margin-top も足して、ジャンプ後に見出しが sticky header に隠れないようにしました。
• mermaid の ELK layout が SSR サイトでは circular JSON でクラッシュする。 Adaptive(ELK)レイアウトに切り替えるといきなり Converting circular structure to JSON が飛びます。掘り下げると、@mermaid-js/layout-elk が ELK のグラフ全体に対して JSON.stringify を行っており、このサイトの <html> は TanStack Start が React でレンダリングしているため documentElement に __reactFiber が乗っていて、シリアライズが循環参照に突き当たっていました。これは React SSR サイト固有の落とし穴です。解決策は参照カウント式の guard で、render の最中だけ JSON.stringify を DOM ノードをスキップする版に差し替えること。

prerender は 111 個のファイルを生成し、1 つも配信されなかった#

実装の途中で、かなり馬鹿げた発見にぶつかりました。docker build の中の prerender は速くきれいに走っている(7.8 秒、111 ファイル、エラーゼロ)し、.output/public/blog/index.html も確かに生成されています。ところが実際に /blog/index.html をリクエストすると必ず 404 が返り、しかも /en を 2 回続けて叩くと md5 が違う。つまり、リクエストのたびに SSR し直していて、あの 111 ファイルは 1 つも配信されたことがなかったわけです。根本原因は、Nitro が静的アセットを登録するリストを、prerender がファイルを書く前にスキャンし終えていたこと。大量のファイルを生成しても誰も配信せず、build 時間を純粋に浪費したうえ、build 中に本番サイトに接続して記事一覧を取りに行かせていました。

そこで prerender をまるごと取り除き、純粋な ISR に切り替えました。ここで先に ISR の仕掛けを説明しておきます。公式のやり方は、私の環境では通らないからです。

救ってくれたのは Nitro の node-server preset でした。SWR が内蔵されていて routeRules 一行で片付き、しかもバックグラウンド再生成が自分のサーバーの中で起きます。

// vite.config.start.ts —— ISR は 1 行で済む。自前で 100 行書く必要はない
const ISR_ROUTE_RULES = {
  ...swrRules(ISR_PAGES.flatMap(localeVariants), 3600),        // UI ページ:1 時間
  ...swrRules(localeVariants('blog'), 300),                    // 一覧ページ:新着記事を早く出したい → 5 分
  ...swrRules(localeVariants('blog').map((p) => `${p}/**`), 3600), // 記事ページ:内容はほぼ動かない → 1 時間
};

サイト全体のリクエストの流れはこうなりました。Rust が唯一の本物のバックエンドで、Node/Nitro はレンダリングの殻が 1 枚あるだけ(これがまさに私の言う「ビジネスロジックは全部 Rust、前段の Node はレンダリングだけ」の実装形です)。

ここには展開する価値のある落とし穴が 3 つあります。

一覧ページが空の殻をキャッシュしていた。 ISR がキャッシュした /blog は最初、中身が空でした。Blog コンポーネントが useEffect の中でデータを取っていて、useEffect は server では実行されないからです → SSR は loading のスケルトンしか吐きません(prerender でも同じで、あれも useEffect を走らせないので救えません)。解決策はデータ取得をルートの loader に移し、useLoaderData で初期データを流し込むこと。/blog の SSR は 19,541 bytes の空の殻から、74,242 bytes、見出しと 8 本の記事リンク入りに変わりました。

公開したら即反映:オンデマンド再生成。 TTL だけでは足りません。新しい記事はすぐにクローラーから見えてほしい。やり方は、Nitro の server route /_revalidate を 1 本用意し(header の secret で保護。/api/* に置かないのは意図的で、nginx が /api/ を全部 Rust に送ってしまうためフロントエンドまで届かないからです)、Rust バックエンドが記事の公開/更新に成功したあと fire-and-forget でそれを叩いてキャッシュを消す、というもの。しかもこれは 14 個の書き込みエンドポイントに個別に付けるのではなく、axum の middleware として実装しました。1 つずつ付けていけば必ず漏れますし、漏れてもエラーは出ず、ただ静かに更新されなくなるだけです。

キャッシュルールはホワイトリストにし、/** は使わない。 サイト全体を包む書き方(/**)は fail-open です。今後 cookie を読むページやユーザーデータを render するページを追加すると、既定で公開キャッシュされ、しかも誰も気づかない。ホワイトリストならその逆で、新しいページは既定でキャッシュされません。明示的にキャッシュしないのは、/(cookie / Accept-Language を読んで言語振り分けをするので、これをキャッシュするのは最初の訪問者の言語を全世界に配るのと同じ)、/admin、/auth です。

MDX:eval するパイプラインと、返したい借金#

ここまで記事はまだ react-markdown でレンダリングしていました。その後 <Note>、<Annot>、<Diff>、<Chart> といった独自 block が欲しくなり(読者の没入感を十分に深くするため)、MDX のパイプラインを 1 本重ねました(記事ごとの opt-in で、format=mdx の記事だけが通ります)。このパイプラインが本稿でいちばん技術的な部分で、しかも私の理解には最初から訂正すべき点がありました。

コンパイルは server でのみ行う。 @mdx-js/mdx のコンパイラは micromark + acorn で非常に重く、client bundle に入れるべきではありません。そこで TanStack の createServerFn を使いました。SSR では in-process で走り、client 側のナビゲーションでは RPC で server に戻ってコンパイル結果を取ってきて、function-body の文字列(シリアライズ可能で、dehydrate して HTML に埋め込める)を生成します。実行は client で行う。フロントエンドはその文字列を受け取って runSync で React コンポーネントとして実行しますが、runSync の内部は new Function、つまり client 側の eval です。

// server-only:コンパイラは重いので client bundle に入れない。出力の function-body 文字列はシリアライズ可能
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 で同期的にコンポーネント化(SSR でも hydration でも動く);⚠️ 内部は new Function = eval
const { default: Content } = runSync(compiled, jsxRuntime);

ついでにエディタ方面の寄り道も書いておきます。一度 MDXEditor(市場で唯一 MDX ネイティブな WYSIWYG エディタ)を入れて spike してみたのですが、依存が 131 個あり、しかも私の独自 block をすべて「歯車 + ラベル」の汎用 UI にレンダリングしてしまい、本物のコンポーネントにはなりません。私自身 Monaco の見た目のほうが好みでもありました。そのあと腑に落ちました。MDXEditor は「MDX を動かす」ための必要条件では最初からなかったのです。Monaco で MDX のソースを書き、レンダラー(compileMdx + runSync)がそれを描く。これで十分でした。spike はきれいに撤収し、Monaco を残しました。ほかにいくつかの決定として、MDX のコンパイルに失敗したら自動で markdown にフォールバック(タグの打ち間違い 1 つで記事全体を吹き飛ばさない)、MDX 記事と markdown 記事は同じ基礎コンポーネント群を共有(shiki のハイライト、mermaid、リンクカード、見出しアンカー)。

その返したい借金は、この runSync にあります。

では、この eval をどう畳むか?最初に考えたのは islands でした。interactive な block を「CSS + bundle 済みの vanilla JS」に書き換え、重い block は registry でマウントする。ただしこれは大量の書き換えが必要で、挙動のリグレッションリスクもあります。その後、はるかにきれいな道に思い当たりました。eval が存在するのは、単に私が MDX を function-body にコンパイルしているからです(あの形式は new Function でなければ動かせない)。もし「本物の ES module」にコンパイルすれば、client は import() で読み込める——そして同一オリジンの import() は、厳格な CSP script-src 'self' の下でも許可されます(それはモジュール読み込みであって eval ではないからです)。 パイプライン全体も、すべての block も、すべてのアニメーションもまったく触らずに済み、書き換えゼロ・リグレッションゼロ。islands はこの道が壁にぶつかったときの退避路にすぎません。目標のフローはこうです。

(これはまだ着手しておらず、TODO に入れました。同じ目的のために Astro も改めて真剣に評価しています。Astro はネイティブに islands で、生まれつき CSP と相性がいい。ですが Astro は独立したフレームワークで独立した build を持ち、既存の TanStack Start には埋め込めません。「blog だけ Astro」は実務上サイトを 2 つのアプリに割るのと同じで、共有している Header / 目次 / リアクション / コメントは全部 island に書き直し、i18n / ISR / SEO / Rust データ層も全部作り直しになります。牛刀ぎゅうとうで鶏にわとりを割さいたうえに厨房まで解体する話で、dynamic-import のほうがコスパが圧倒的に高い。)

初回フレームがもうチラつかない:入場デバッグの長征#

以上はすべて本番に出ましたが、本当に深夜まで削られたのは「記事に入るその一瞬」でした。ここから先はレンダリングの時系列の落とし穴ばかりで、本稿の核心でもあります。まず結果から。左が当時の惨状、右が仕上げ後です。

ここまで書いていて気になりました。同じくコンテンツ中心のサイトで、みなさんは最終的にどのマスに止まっているのでしょう。

まとめ:3 度の書き直しの決算#

このレンダリングの長征は、実のところ層の違う 3 つの勘定でした。

1. SEO と初期表示は SSG/ISR の配当。hydration は、その引き換えに手に入る新種のバグ一式。 これ以降、記事の本文もタイトルも hreflang も本当に HTML に render され、クローラーは JS を走らせなくても見られます。代償は Node のレンダリング層が 1 枚増えたことと、「SSR が送ったものと client が描くものは一字一句一致していなければならない」という、以前は存在しなかった種類のバグです。
2. 測れ、推測するな。 この一晩でいちばん価値があったのは、無理にでも立ち止まって「これは本当に直ったのか、それとも迂回したか/たまたま当たっただけか?」と問い返したことです。それが、印象で下した 2 つの誤診(3 つのバグの偽の修正、スクロールのシリアライズバグ)を押し戻し、アブレーションテストと Playwright で真相を測らせました。
3. 繰り返し噛みついてくるルールがいくつか: useEffect は server で走らないので、それでデータを取っているページは SSR も prerender も空の殻しか吐かない。fail-open なサイト全体のキャッシュルールは地雷。パスのプレフィックスでキャッシュを消すときは、高頻度のエンドポイントを除外し忘れない。

返し切っていない借金も、正直に並べておきます。MDX の runSync は client の eval で、今のところ CSP をそもそも有効にしていないので当面は無害ですが、この eval は厳格な CSP を入れる前に畳んでおきたい。計画は MDX を ESM モジュールにコンパイルし、runSync を import() で置き換えること(islands は退避路にすぎません)。ISR のキャッシュはまだメモリ上にあり、デプロイや再起動のたびにサイト全体がゼロに戻ります(fs driver をまだ繋いでいない)。古い SEOHead(react-helmet)も完全には引退していません。レンダリングというテーマはおそらく永遠に改修し終わらないでしょう。それでも少なくとも今は、1 本の記事がデータベースからあなたの画面まで届くまでの一歩一歩が、なぜそういう形をしているのか、私は全部わかっています。