Indlæsning af WASM-moduler i React

Den browserstandardiserede måde at indlæse et WASM-modul på er WebAssembly.instantiateStreaming(fetch(url), importObject). Det streamer WASM-binærfilen, mens den downloades, starter kompileringen med det samme og returnerer et objekt, der indeholder modulet og instansen. Det er den mest effektive indlæsningsmetode til produktionsbrug.

Bundlere som Vite og webpack understøtter import af WASM-filer som ES-moduler med syntaks til dynamisk import: import('./module.wasm'). Bundleren håndterer indlæsningsmekanikken. Denne tilgang integreres naturligt med kodedeling — WASM-modulet indlæses først, når koden, der importerer det, bliver kørt.

Indlæsning af et WASM-modul er en asynkron handling, der hører hjemme i en useEffect-hook. Hent og instantiér modulet inde i effekten, gem de eksporterede funktioner i tilstanden eller en ref, og opdatér komponenten, når initialiseringen er fuldført. Det tomme afhængighedsarray sikrer, at modulet kun indlæses én gang pr. montering af komponenten.

Gem WASM-instansen i en useRef for at undgå nye gengivelser under initialiseringen, eller i en variabel på modulniveau, hvis instansen er en singleton, der deles på tværs af applikationen. Det fungerer også at gemme den i useState, men det medfører en ekstra gengivelse, når instansen bliver tilgængelig — det er acceptabelt i simple tilfælde.

For komponenter, der kræver et WASM-modul for at fungere, skal du pakke komponenten ind i React.lazy og gengive den inde i en Suspense-grænse. WASM-modulet kan indlæses som en del af den dynamiske import. Suspense viser et reserveskelet, mens modulet initialiseres, hvilket giver en enkel indlæsningsoplevelse.

WASM-moduler tager 100-500 ms at indlæse og instantiere på en typisk forbindelse, afhængigt af modulets størrelse og enhedens hastighed. Vis altid en indlæsningsindikator (skelet, spinner eller fremdriftsbjælke), mens initialiseringen er i gang. Hvis brugergrænsefladen blokeres under WASM-initialiseringen uden visuel feedback, opleves det som en fastfrysning.

Efter instansiering er WASM-funktioner tilgængelige via instance.exports.myFunction(). Når du bruger wasm-bindgen (Rust-værktøjskæden), eksporterer det genererede JavaScript-modul med forbindelseskode funktionerne direkte med korrekt typekonvertering. Du kalder dem som almindelige JavaScript-funktioner med de typer, der er defineret i Rust-kilden.

Kald WASM-funktioner fra React-hændelseshåndterere på samme måde som ethvert synkront funktionskald: function handleClick() { const result = wasmInstance.current.processImage(imageData); setResult(result); }. WASM-funktionskald er synkrone — de blokerer den kaldende tråd, indtil beregningen er fuldført, hvilket er endnu en grund til at køre dem i en Worker ved lange operationer.

WASM-initialisering kan mislykkes: Hentningen kan mislykkes, modulet kan være inkompatibelt, eller browseren understøtter måske ikke en nødvendig funktion. Pak WASM-afhængige komponenter ind i en React-fejlgrænse for at opfange initialiseringsfejl og vise en reservevisning. Log fejlen til fejlfinding, og sørg om muligt for en vej til kontrolleret degradering.

Vite kræver to udvidelsesmoduler for at håndtere WASM-moduler korrekt: vite-plugin-wasm håndterer import af WASM-filer, og vite-plugin-top-level-await aktiverer await på øverste niveau, som bruges af noget WASM-forbindelseskode. Installér begge, og føj dem til plugins-arrayet i vite.config.ts.

I webpack-projekter skal du aktivere eksperimentet asyncWebAssembly i webpack.config.js: experiments: { asyncWebAssembly: true }. Det gør det muligt at bruge import() til WASM-filer, mens browseren indlæser modulet asynkront. Create React App-projekter kræver, at du ejecter eller bruger CRACO for at tilføje denne konfiguration.

Indlæs WASM med WebAssembly.instantiateStreaming(fetch(url)) eller dynamisk import i useEffect. Gem instansen i useRef eller som en singleton på modulniveau. Vis indlæsningstilstanden under initialiseringen på 100-500 ms. Få adgang til eksporter via instance.exports.fn(). Brug fejlgrænser ved initialiseringsfejl. Konfigurér Vite med vite-plugin-wasm og vite-plugin-top-level-await.