WASM-Module in React laden

Die standardmäßige Methode des Browsers zum Laden eines WASM-Moduls ist WebAssembly.instantiateStreaming(fetch(url), importObject). Dabei wird das WASM-Binärformat während des Downloads gestreamt, die Kompilierung sofort begonnen und ein Objekt mit dem Modul und der Instanz zurückgegeben. Für den Produktionseinsatz ist dies die effizienteste Lademethode.

Bundler wie Vite und webpack unterstützen das Importieren von WASM-Dateien als ES-Module mit der Syntax für dynamische Imports: import('./module.wasm'). Der Bundler übernimmt die technischen Details des Ladens. Dieser Ansatz lässt sich nahtlos mit Code-Splitting kombinieren – das WASM-Modul wird erst geladen, wenn der importierende Code ausgeführt wird.

Das Laden eines WASM-Moduls ist eine asynchrone Operation und gehört in einen useEffect-Hook. Rufen Sie Fetch und die Instanziierung des Moduls innerhalb des Effects auf, speichern Sie die exportierten Funktionen in einem State oder einer Ref und aktualisieren Sie die Komponente, sobald die Initialisierung abgeschlossen ist. Das leere Dependency-Array stellt sicher, dass das Modul pro Mounting der Komponente nur einmal geladen wird.

Speichern Sie die WASM-Instanz in einer useRef, um beim Initialisieren erneute Renderings zu vermeiden, oder in einer Variablen auf Modulebene, wenn die Instanz als Singleton von der gesamten Anwendung gemeinsam genutzt wird. Das Speichern in useState funktioniert ebenfalls, verursacht aber ein zusätzliches Rendering, sobald die Instanz verfügbar ist – für einfache Fälle ist das akzeptabel.

Bei Komponenten, die für ihre Funktion ein WASM-Modul benötigen, umschließen Sie die Komponente mit React.lazy und rendern sie innerhalb einer Suspense-Grenze. Das WASM-Modul kann als Teil des dynamischen Imports geladen werden. Suspense zeigt ein Skeleton als Fallback an, während das Modul initialisiert wird, und sorgt so für eine reibungslose Ladeerfahrung.

WASM-Module benötigen bei einer typischen Verbindung je nach Modulgröße und Gerätegeschwindigkeit 100–500 ms zum Laden und Instanziieren. Zeigen Sie während der Initialisierung immer einen Ladeindikator an, etwa ein Skeleton, einen Spinner oder einen Fortschrittsbalken. Wenn Sie die UI ohne visuelles Feedback durch die WASM-Initialisierung blockieren, entsteht der Eindruck, die Anwendung hänge.

Nach der Instanziierung sind WASM-Funktionen über instance.exports.myFunction() verfügbar. Bei Verwendung von wasm-bindgen (Rust-Toolchain) exportiert das generierte JavaScript-Glue-Modul die Funktionen direkt und übernimmt die korrekte Typkonvertierung. Sie rufen sie wie gewöhnliche JavaScript-Funktionen mit den in der Rust-Quelle definierten Typen auf.

Rufen Sie WASM-Funktionen aus React-Event-Handlern wie jeden synchronen Funktionsaufruf auf: function handleClick() { const result = wasmInstance.current.processImage(imageData); setResult(result); }. WASM-Funktionsaufrufe sind synchron – sie blockieren den aufrufenden Thread, bis die Berechnung abgeschlossen ist. Das ist ein weiterer Grund, lang laufende Operationen in einem Worker auszuführen.

Die WASM-Initialisierung kann fehlschlagen: Der Fetch kann scheitern, das Modul kann inkompatibel sein oder dem Browser kann eine erforderliche Funktion fehlen. Umschließen Sie WASM-abhängige Komponenten mit einer React Error Boundary, um Initialisierungsfehler abzufangen und einen Fallback anzuzeigen. Protokollieren Sie den Fehler zur Fehlersuche und bieten Sie nach Möglichkeit einen graceful Degradation-Pfad an.

Vite benötigt zwei Plugins, um WASM-Module korrekt zu verarbeiten: vite-plugin-wasm verarbeitet WASM-Dateiimporte und vite-plugin-top-level-await aktiviert Top-Level-Await, das von manchem WASM-Glue-Code verwendet wird. Installieren Sie beide Plugins und fügen Sie sie in vite.config.ts zum Array plugins hinzu.

Aktivieren Sie bei webpack-Projekten das Experiment asyncWebAssembly in webpack.config.js: experiments: { asyncWebAssembly: true }. Dadurch können Sie WASM-Dateien mit import() importieren, wobei der Browser das Modul asynchron lädt. Für Create-React-App-Projekte müssen Sie eject ausführen oder CRACO verwenden, um diese Konfiguration hinzuzufügen.

Welchen Vorteil bietet WebAssembly.instantiateStreaming() gegenüber WebAssembly.instantiate()?

Laden Sie WASM mit WebAssembly.instantiateStreaming(fetch(url)) oder einem dynamischen Import in useEffect. Speichern Sie die Instanz in useRef oder einem Singleton auf Modulebene. Zeigen Sie während der 100–500 ms dauernden Initialisierung einen Ladezustand an. Greifen Sie über instance.exports.fn() auf Exporte zu. Verwenden Sie Error Boundaries für Initialisierungsfehler. Konfigurieren Sie Vite mit vite-plugin-wasm und vite-plugin-top-level-await.