RemixのResource RouteでOGP画像を生成する際にハマったWASM問題とその解決法
著者: ClaudeMix Team |
workers-ogをインストールしてRemixのResource RouteでOGP画像を生成しようとすると、ローカルでは動くのにWranglerビルドでCould not resolve "workers-og"エラーが出た。vite.config.tsのssr.external: ["workers-og"]で解決した。
症状
- 使用スタック: Remix v2 + Vite / Cloudflare Pages・Workers /
workers-og(内部依存:satori→yoga-wasm-web→ WASMバイナリ) - ローカル開発サーバー: 正常動作
- Wrangler(Cloudflare Workersエミュレータ)ビルド: エラー
X [ERROR] Could not resolve "workers-og"
The package "workers-og" wasn't found on the file system but is built into node.
Add "workers-og" to the "external" option to exclude it from the bundle...
X [ERROR] Could not load yoga-ZMNYPE6Z.wasm (imported by /__vite-browser-external:yoga-wasm-web):
Reading from "yoga-wasm-web" is not handled by any plugin原因
workers-ogが内部で使うsatori→yoga-wasm-webがWASMバイナリを含んでおり、バンドラーがこれを通常のモジュールとして処理しようとして、エッジランタイムのWASMロード方式と競合していた。Node.js環境の開発サーバーはWASMを直接読み込めるため、ローカルでは問題が起きない。Cloudflare Workersは【事前コンパイル済みWASMのみサポートし、動的WASM生成は禁止】というランタイム制約があり、この制約自体がずれの根本原因。
解決策
エラーメッセージ自体にAdd "workers-og" to the "external" optionとヒントが書かれていた。
// vite.config.ts
ssr: {
resolve: {
externalConditions: ["workerd", "worker"],
},
+ external: ["workers-og"],
},ssr.external: Viteにworkers-ogをバンドル対象から除外させ、Cloudflare Workersのランタイムが提供するものとして扱うexternalConditions: ["workerd", "worker"]: Cloudflare Workers環境(workerd)用のパッケージ解決条件を指定し、Workers用のエクスポートを選択させる
検証は「Vite開発 → Wrangler → ビルド → デプロイ」の順で段階的に動作確認した。
学び
- エラーメッセージには解決策そのものが書かれていることが多い。対症療法(別ライブラリへの乗り換え、設定の当てずっぽうな変更)に走る前に、まずエラー文面を精読する
- Cloudflare Workers専用のWASM依存ライブラリ(
workers-og、@cloudflare/ai等)は、ssr.externalに追加するのが定石。新しいWASM利用ライブラリを追加する際は必ず検討する - この「WASM/Node API制約」は個別のバグではなくCloudflare Workersのランタイム仕様そのものであり、Shikiのシンタックスハイライトでの同じ問題(ビルド時HTML変換で解決)や、Cloudflare Pagesでfs系APIが使えない問題にも共通する構造的制約