ReactでWASMモジュールを読み込む

ブラウザー標準のWASMモジュール読み込み方法は、WebAssembly.instantiateStreaming(fetch(url), importObject)です。WASMバイナリをダウンロードしながらストリーミングし、すぐにコンパイルを開始します。その後、モジュールとインスタンスを含むオブジェクトで解決されます。本番環境で最も効率的な読み込み方法です。

Viteやwebpackなどのバンドラーは、動的インポート構文import('./module.wasm')を使って、WASMファイルをESモジュールとしてインポートできます。読み込みの仕組みはバンドラーが処理します。この方法はコード分割とも自然に統合でき、WASMモジュールはインポート元のコードが実行されたときだけ読み込まれます。

WASMモジュールの読み込みは非同期処理なので、useEffectフック内で行う必要があります。エフェクト内でモジュールをフェッチしてインスタンス化し、エクスポートされた関数をstateまたはrefに保存し、初期化が完了したらコンポーネントを更新します。空の依存配列により、コンポーネントのマウントごとにモジュールが一度だけ読み込まれます。

初期化時の再レンダリングを避けるには、WASMインスタンスをuseRefに保存します。または、アプリケーション全体で共有するシングルトンの場合は、モジュールレベルの変数に保存します。useStateに保存する方法も機能しますが、インスタンスが利用可能になったときに余分な再レンダリングが発生します。単純なケースでは許容できます。

WASMモジュールがないと動作しないコンポーネントでは、そのコンポーネントをReact.lazyでラップし、Suspense境界内でレンダリングします。動的インポートの一部としてWASMモジュールを読み込むこともできます。モジュールの初期化中はSuspenseがフォールバックのスケルトンを表示するため、快適な読み込み体験を提供できます。

WASMモジュールの読み込みとインスタンス化には、一般的な接続環境で100～500ミリ秒かかります。所要時間はモジュールのサイズとデバイスの速度によって異なります。初期化中は必ず、ローディングインジケーター（スケルトン、スピナー、プログレスバーなど）を表示してください。視覚的なフィードバックなしにWASMの初期化でUIをブロックすると、ユーザーには処理が停止したように見えます。

インスタンス化が完了すると、WASM関数はinstance.exports.myFunction()から利用できます。wasm-bindgen（Rustツールチェーン）を使用する場合、生成されたJavaScriptのグルーコードモジュールが、適切な型変換を行ったうえで関数を直接エクスポートします。Rustソースで定義された型を使い、通常のJavaScript関数と同じように呼び出せます。

ReactのイベントハンドラーからWASM関数を、同期関数を呼び出す場合と同じように呼び出します。function handleClick() { const result = wasmInstance.current.processImage(imageData); setResult(result); }WASM関数の呼び出しは同期的であり、計算が完了するまで呼び出し元のスレッドをブロックします。そのため、長時間かかる処理はWorkerで実行することをおすすめします。

WASMの初期化は、フェッチの失敗、モジュールの非互換性、ブラウザーの機能不足などによって失敗することがあります。WASMに依存するコンポーネントをReactのError Boundaryでラップし、初期化の失敗を捕捉してフォールバックを表示します。デバッグ用にエラーを記録し、可能であれば適切な代替手段を用意してください。

ViteでWASMモジュールを正しく扱うには、2つのプラグインが必要です。vite-plugin-wasmはWASMファイルのインポートを処理し、vite-plugin-top-level-awaitは一部のWASMグルーコードで使用されるトップレベルawaitを有効にします。両方をインストールし、vite.config.tsのplugins配列に追加してください。

webpackプロジェクトでは、webpack.config.jsでasyncWebAssembly実験機能を有効にします。experiments: { asyncWebAssembly: true }これにより、import()でWASMファイルをインポートでき、ブラウザーがモジュールを非同期で読み込めるようになります。Create React Appプロジェクトでは、ejectするかCRACOを使用してこの設定を追加する必要があります。

WebAssembly.instantiate()に対するWebAssembly.instantiateStreaming()の利点は何でしょうか？

WebAssembly.instantiateStreaming(fetch(url))またはuseEffect内の動的インポートを使ってWASMを読み込みます。インスタンスはuseRefまたはモジュールシングルトンに保存します。100～500ミリ秒の初期化中はローディング状態を表示します。エクスポートにはinstance.exports.fn()からアクセスします。初期化の失敗にはError Boundaryを使用します。Viteにはvite-plugin-wasmとvite-plugin-top-level-awaitを設定します。