ビルド時コンテンツバンドルは何を優先したのか:ファイルシステムなき環境への適応という価値選択

著者: ClaudeMix Team |

Cloudflare Workersにファイルシステムが存在しないという制約に対し、コンテンツの読み込みをランタイムのファイルI/Oからビルド時のモジュール変換へ移すことを優先した。

① ビルド時コンテンツバンドルは何を優先したか

一般的なNode.jsサーバーでは、fs.readFile でコンテンツファイルを自由に読み込める。ローカル開発環境ではこれが当たり前に動く。

Cloudflare WorkersはV8 Isolate上で動作するステートレスな実行環境で、fs・path・stream といったNode.js標準のファイルシステムAPIを提供しない。従来のサーバーが持っていた「ランタイム時に何でもできる自由」は、この環境には存在しない。

  • 【優先した価値】: エッジ実行環境が要求する制約への適合。ファイルの内容をビルド時にコードへ埋め込み、ランタイムはモジュール参照だけで完結させる
  • 【犠牲にした価値】: ランタイムでの動的なファイルアクセス。コンテンツを更新するたびに再ビルドが必要になり、CMS等による「公開即反映」のフローとは相性が悪くなる

② ClaudeMixでやったこと

Before: fs.readFile でMarkdownファイルを直接読み込んでいた。Cloudflare Pagesへのデプロイ時に Could not resolve "fs" 等のエラーが20以上のファイルで発生していた。

// app/data-io/blog/posts/fetchPosts.server.ts(変更前)
import fs from 'fs/promises';
import matter from 'gray-matter';

export async function fetchPosts() {
  const files = await fs.readdir('content/blog/posts');
  const posts = await Promise.all(
    files.map(async (file) => {
      const content = await fs.readFile(`content/blog/posts/${file}`, 'utf-8');
      return matter(content);
    })
  );
  return posts;
}

After: プリビルドスクリプトでMarkdownを走査し、型安全なTypeScriptモジュールとして書き出す構成に変更した。データアクセス層はそのモジュールをimportするだけになった。

// scripts/prebuild/generate-blog-posts.js(抜粋)
const posts = await Promise.all(
  files.map(async (file) => {
    const content = await fs.readFile(path.join(postsDir, file), 'utf-8');
    const { data, content: markdown } = matter(content);
    return { slug: file.replace('.md', ''), frontmatter: data, content: markdown };
  })
);

await fs.writeFile('app/generated/blog-posts.ts', `
export const posts = ${JSON.stringify(posts, null, 2)};
export function getPostBySlug(slug) { return posts.find(p => p.slug === slug); }
`);
// app/data-io/blog/posts/fetchPosts.server.ts(変更後)
import { getAllPosts } from '~/generated/blog-posts';

export function fetchPosts() {
  return getAllPosts();
}

③ 技術的負債

  • 【解消した負債】: ファイルシステム非互換によるデプロイ失敗。記事読み込み速度も実測: 10〜50ms(ファイルI/O) → 約1ms(インメモリ)
  • 【新たに生まれた負債(あれば)】: サーバーバンドルサイズが33.30 kBから204.75 kBへ増加した。全記事分のコンテンツと依存関係がバンドルに含まれるためで、記事数が増えるほどこのサイズも増加する。またコンテンツ更新のたびに再ビルドが必要になった

④ 経営翻訳

各拠点が資料を都度倉庫へ問い合わせて取り寄せていた業務体制を、あらかじめ手元のバインダーへ全資料をまとめておく体制へ切り替えた。倉庫へのアクセス自体ができなくなったための対応であり、取り寄せの手間はなくなった一方、バインダー自体の分量は増えた。

実際には資料の取り出し時間が10〜50msから約1msまで短縮され、10〜50倍速くなった。手元にまとめておく方式への切り替えが効いた。

この「制約への適応」という発想は、後に取り組むことになるShikiのWASM制約をビルド時HTML変換で解決した記録や、OGP画像生成のWASM問題でも形を変えて活きることになる。

各拠点が資料を都度倉庫へ問い合わせて取り寄せていた業務体制を、 あらかじめ手元のバインダーへ全資料をまとめておく体制へ切り替えることにした。

資料の取り出しにかかる時間: 10〜50ms