ビルド時HTML変換は何を優先したのか:WASM制約を実行タイミングの移動で越える価値選択

著者: ClaudeMix Team |

Cloudflare Workersが動的なWebAssembly生成を禁止しているという制約に対し、Markdown→HTML変換の実行タイミングをランタイムからビルド時へ移すことを優先した。

① ビルド時HTML変換は何を優先したか

一般的なSSRブログでは、記事の loader がリクエストのたびにMarkdownをHTMLへ変換する。シンタックスハイライトライブラリ(Shiki)は内部で正規表現エンジンとしてWebAssemblyを使っており、初期化時に動的にWASMを生成する。

Cloudflare Workersはセキュリティとパフォーマンスのため、事前コンパイルされたWASMのみをサポートし、ランタイムでの動的なWASM生成を禁止している。この制約のもとでは、ランタイム変換という一般的な実装はそのまま動かない。

  • 【優先した価値】: Workers環境という実行環境の制約に適合すること。処理の実行タイミングをランタイムからビルド時へ移すことで、WASM生成が許可されている環境(ビルドマシン)でのみShikiを動かす
  • 【犠牲にした価値】: ランタイムでの動的なコンテンツ変換。記事を追加・更新するたびに再ビルドが必要になり、「ユーザーからのリクエストを起点に処理する」という自由度を手放す

② ClaudeMixでやったこと

Before: loader 内でMarkdown→HTML変換を都度実行しており、Cloudflare Pagesへのデプロイ後に記事詳細ページを開くと CompileError: WebAssembly.instantiate(): Wasm code generation disallowed by embedder でクラッシュしていた。

// app/routes/blog.$slug.tsx(変更前・概念)
export async function loader({ params }: LoaderFunctionArgs) {
  const markdown = await getPostMarkdown(params.slug);
  const html = await convertMarkdownToHtml(markdown); // ここでShikiのWASM初期化が走る
  return { html };
}

After: scripts/prebuild/generate-blog-posts.js にビルド時変換処理を実装し、Shikiインスタンスをシングルトンで管理するようにした。

import { createHighlighter } from 'shiki/bundle/full';

let highlighter = null;

async function getHighlighter() {
  if (!highlighter) {
    highlighter = await createHighlighter({
      themes: ['github-dark'],
      langs: ['javascript', 'typescript', 'html', 'css', 'markdown', 'bash', 'json', 'tsx', 'diff', 'yaml', 'xml'],
    });
  }
  return highlighter;
}

async function generateBlogPosts() {
  await getHighlighter(); // 並列処理前に一度だけ初期化

  const posts = await Promise.all(
    markdownFiles.map(async (file) => {
      const htmlContent = await convertMarkdownToHtml(content);
      return { slug, content: htmlContent };
    })
  );
}

Promise.all による21記事の並列処理を、初期化前に開始すると複数の処理が同時に getHighlighter() を呼び出してハングアップした。並列処理を開始する前に一度だけ初期化を呼び出すことで、この競合を解消した。

③ 技術的負債

  • 【解消した負債】: ランタイムでのWASM実行という、Workers環境と根本的に噛み合わない処理経路。ビルド時変換への移行により、記事詳細ページのクラッシュが解消した
  • 【新たに生まれた負債(あれば)】: 記事の追加・更新のたびに再ビルドが必要になった。また、Shikiのバージョンアップやハイライト対象言語の追加を行う際は、ビルドスクリプト側の設定変更が必要になる

本文から独立に数え直せる定量的なBefore/After値(クラッシュ発生率の変化等)は存在しない。ビルド時変換の性能自体は実測済みで、21記事の変換は最速1ms・最長322ms・平均30〜40msで完了し、合計で数秒に収まっているが、対応するBefore値(ランタイム変換の所要時間)は計測不能(クラッシュしていたため)なので比較には使わない。

④ 経営翻訳

特定の加工機械が、稼働中の工場フロアでは使用禁止という規則がある工場を借りて操業することになった。製品の加工自体は、稼働開始前の準備段階で全て終わらせておき、フロアでは完成品を並べるだけにする体制に切り替えることにした。

この切り替えの発想は、後に別の生成処理(OGP画像生成のWASM問題)でも活きることになる。ただしそちらは準備段階への移動ではなく、ビルド設定側で処理を外部化する別のアプローチで解決している。