Ladda WASM-moduler i React

Det webbläsarstandardiserade sättet att läsa in en WASM-modul är WebAssembly.instantiateStreaming(fetch(url), importObject). Detta strömmar WASM-binären medan den laddas ned, börjar kompilera omedelbart och returnerar ett objekt som innehåller modulen och instansen. Det är den effektivaste inläsningsmetoden för produktionsanvändning.

Bundlers som Vite och webpack stöder import av WASM-filer som ES-moduler med syntax för dynamisk import: import('./module.wasm'). Bundlern hanterar inläsningen. Metoden integreras naturligt med koddelning — WASM-modulen laddas endast när koden som importerar den körs.

Att läsa in en WASM-modul är en asynkron operation som hör hemma i en useEffect-hook. Hämta och instansiera modulen i effekten, lagra de exporterade funktionerna i tillstånd eller i en ref och uppdatera komponenten när initieringen är klar. Den tomma beroendearrayen säkerställer att modulen endast läses in en gång per komponentmontering.

Lagra WASM-instansen i en useRef för att undvika nya renderingar vid initiering, eller i en variabel på modulnivå om instansen är en singleton som delas av hela applikationen. Det fungerar också att lagra den i useState, men det orsakar en extra rendering när instansen blir tillgänglig — vilket är acceptabelt i enkla fall.

För komponenter som behöver en WASM-modul för att fungera kan du omsluta komponenten med React.lazy och rendera den i en Suspense-gräns. WASM-modulen kan läsas in som en del av den dynamiska importen. Suspense visar ett reservskelett medan modulen initieras, vilket ger en smidig inläsningsupplevelse.

WASM-moduler tar vanligtvis 100–500 ms att läsa in och instansiera, beroende på modulens storlek och enhetens hastighet. Visa alltid en indikator för pågående inläsning (skelett, snurra eller förloppsindikator) medan initieringen pågår. Om användargränssnittet blockeras under WASM-initieringen utan visuell återkoppling upplevs applikationen som låst.

Efter instansieringen är WASM-funktionerna tillgängliga via instance.exports.myFunction(). När wasm-bindgen används (Rust-verktygskedjan) exporterar den genererade JavaScript-gluemodulen funktionerna direkt och hanterar typkonvertering korrekt. Du anropar dem som vanliga JavaScript-funktioner med de typer som definieras i Rust-källan.

Anropa WASM-funktioner från Reacts händelsehanterare precis som ett vanligt synkront funktionsanrop: function handleClick() { const result = wasmInstance.current.processImage(imageData); setResult(result); }. WASM-funktionsanrop är synkrona — de blockerar den anropande tråden tills beräkningen är klar. Det är ytterligare ett skäl att köra dem i en Worker vid långvariga operationer.

WASM-initieringen kan misslyckas: hämtningen kan misslyckas, modulen kan vara inkompatibel eller webbläsaren kan sakna en nödvändig funktion. Omslut WASM-beroende komponenter med en React Error Boundary för att fånga initieringsfel och visa ett reservgränssnitt. Logga felet för felsökning och tillhandahåll om möjligt en ordnad reservlösning.

Vite kräver två plugins för att hantera WASM-moduler korrekt: vite-plugin-wasm hanterar import av WASM-filer och vite-plugin-top-level-await aktiverar top-level await som används av viss WASM-gluekod. Installera båda och lägg till dem i arrayen plugins i vite.config.ts.

För webpack-projekt aktiverar du experimentet asyncWebAssembly i webpack.config.js: experiments: { asyncWebAssembly: true }. Då kan import() användas för WASM-filer, och webbläsaren läser in modulen asynkront. Create React App-projekt kräver att du kör eject eller använder CRACO för att lägga till denna konfiguration.

Läs in WASM med WebAssembly.instantiateStreaming(fetch(url)) eller dynamisk import i useEffect. Lagra instansen i useRef eller i en singleton på modulnivå. Visa inläsningsstatus under initieringen på 100–500 ms. Åtkomst till exporter fås via instance.exports.fn(). Använd Error Boundaries för initieringsfel. Konfigurera Vite med vite-plugin-wasm och vite-plugin-top-level-await.