WASM-modules laden in React

De standaardmanier in de browser om een WASM-module te laden is WebAssembly.instantiateStreaming(fetch(url), importObject). Hierbij wordt het WASM-binaire bestand gestreamd terwijl het wordt gedownload, begint de compilatie meteen en wordt een object geleverd dat de module en de instantie bevat. Dit is de efficiëntste laadwijze voor gebruik in productie.

Bundelaars zoals Vite en webpack ondersteunen het importeren van WASM-bestanden als ES-modules met de syntaxis voor dynamische import: import('./module.wasm'). De bundelaar handelt het laadmechanisme af. Deze aanpak werkt vanzelfsprekend samen met het opsplitsen van code — de WASM-module wordt alleen geladen wanneer de code die de module importeert wordt uitgevoerd.

Het laden van een WASM-module is een asynchrone bewerking die thuishoort in een useEffect-hook. Haal de module op en instantieer deze binnen het effect, sla de geëxporteerde functies op in de status of in een ref en werk de component bij wanneer de initialisatie is voltooid. De lege afhankelijkheidsarray zorgt ervoor dat de module maar één keer per keer dat de component wordt aangekoppeld wordt geladen.

Sla de WASM-instantie op in een useRef om nieuwe weergaven tijdens de initialisatie te voorkomen, of in een variabele op moduleniveau als de instantie een singleton is die in de hele toepassing wordt gedeeld. Opslaan in useState werkt ook, maar veroorzaakt een extra nieuwe weergave wanneer de instantie beschikbaar komt — aanvaardbaar in eenvoudige gevallen.

Voor componenten die een WASM-module nodig hebben om te werken, wikkel je de component in React.lazy en geef je deze weer binnen een Suspense-grens. De WASM-module kan als onderdeel van de dynamische import worden geladen. Suspense toont een skeletweergave als terugval terwijl de module wordt geïnitialiseerd, zodat het laden netjes verloopt.

WASM-modules hebben op een gebruikelijke verbinding 100-500 ms nodig om te laden en te initialiseren, afhankelijk van de omvang van de module en de snelheid van het apparaat. Toon altijd een laadindicator (skeletweergave, laadanimatie of voortgangsbalk) zolang de initialisatie bezig is. Als je de gebruikersinterface blokkeert tijdens de initialisatie van WASM zonder visuele feedback, lijkt de toepassing vast te lopen.

Na de initialisatie zijn WASM-functies beschikbaar via instance.exports.myFunction(). Bij gebruik van wasm-bindgen (de Rust-gereedschapsketen) exporteert de gegenereerde JavaScript-verbindingsmodule de functies rechtstreeks en worden typen correct omgezet. Je roept ze aan als gewone JavaScript-functies, met de typen die in de Rust-broncode zijn gedefinieerd.

Roep WASM-functies vanuit gebeurtenisverwerkers van React aan zoals elke synchrone functieaanroep: function handleClick() { const result = wasmInstance.current.processImage(imageData); setResult(result); }. WASM-functieaanroepen zijn synchroon — ze blokkeren de thread die de aanroep uitvoert totdat de berekening is voltooid. Dat is nog een reden om ze voor lange bewerkingen in een Worker uit te voeren.

De initialisatie van WASM kan mislukken: het ophalen kan mislukken, de module kan incompatibel zijn of de browser kan een functie missen. Plaats componenten die van WASM afhangen binnen een React-foutgrens om initialisatiefouten op te vangen en een terugval te tonen. Registreer de fout voor foutopsporing en bied indien mogelijk een nette terugvalmogelijkheid.

Vite heeft twee plug-ins nodig om WASM-modules goed te verwerken: vite-plugin-wasm verwerkt imports van WASM-bestanden en vite-plugin-top-level-await maakt await op topniveau mogelijk, dat door sommige WASM-verbindingscode wordt gebruikt. Installeer beide en voeg ze toe aan de array plugins in vite.config.ts.

Schakel voor webpack-projecten de asyncWebAssembly-experimentfunctie in webpack.config.js in: experiments: { asyncWebAssembly: true }. Hierdoor kun je WASM-bestanden met import() importeren, waarbij de browser de module asynchroon laadt. Create React App-projecten vereisen dat je eject uitvoert of CRACO gebruikt om deze configuratie toe te voegen.

Laad WASM met WebAssembly.instantiateStreaming(fetch(url)) of met een dynamische import in useEffect. Sla de instantie op in useRef of in een singleton op moduleniveau. Toon een laadstatus tijdens de initialisatie van 100-500 ms. Gebruik instance.exports.fn() om exports te benaderen. Gebruik foutgrenzen voor initialisatiefouten. Configureer Vite met vite-plugin-wasm en vite-plugin-top-level-await.