Ładowanie modułów WASM w React

Standardowym sposobem ładowania modułu WASM w przeglądarce jest WebAssembly.instantiateStreaming(fetch(url), importObject). Ta metoda strumieniuje binarny moduł WASM w miarę jego pobierania, natychmiast rozpoczyna kompilację i zwraca obietnicę rozwiązywaną obiektem zawierającym moduł oraz instancję. Jest to najbardziej wydajna metoda ładowania w środowisku produkcyjnym.

Bundlery takie jak Vite i webpack obsługują importowanie plików WASM jako modułów ES za pomocą składni dynamicznego importu: import('./module.wasm'). Bundler obsługuje mechanizm ładowania. To podejście naturalnie integruje się z dzieleniem kodu — moduł WASM jest ładowany dopiero wtedy, gdy zostanie wykonany kod go importujący.

Ładowanie modułu WASM jest operacją asynchroniczną, która powinna odbywać się w hooku useEffect. Wewnątrz efektu należy pobrać i zainicjalizować moduł, przechować wyeksportowane funkcje w stanie lub refie oraz zaktualizować komponent po zakończeniu inicjalizacji. Pusta tablica zależności gwarantuje, że moduł zostanie załadowany tylko raz podczas montowania komponentu.

Instancję WASM należy przechowywać w useRef, aby uniknąć ponownego renderowania podczas inicjalizacji, albo w zmiennej na poziomie modułu, jeśli instancja jest singletonem współdzielonym w całej aplikacji. Przechowywanie jej w useState również działa, ale powoduje dodatkowe ponowne renderowanie, gdy instancja stanie się dostępna — w prostych przypadkach jest to akceptowalne.

W przypadku komponentów wymagających do działania modułu WASM należy opakować komponent w React.lazy i renderować go wewnątrz granicy Suspense. Moduł WASM można załadować w ramach dynamicznego importu. Suspense wyświetla zastępczy szkielet podczas inicjalizacji modułu, zapewniając płynny proces ładowania.

Ładowanie i inicjalizacja modułów WASM zajmują zwykle 100–500 ms przy typowym połączeniu, w zależności od rozmiaru modułu i szybkości urządzenia. Podczas trwania inicjalizacji należy zawsze wyświetlać wskaźnik ładowania (szkielet, spinner lub pasek postępu). Blokowanie interfejsu podczas inicjalizacji WASM bez wizualnego sygnału sprawia wrażenie zawieszenia aplikacji.

Po inicjalizacji funkcje WASM są dostępne za pośrednictwem instance.exports.myFunction(). W przypadku korzystania z wasm-bindgen (łańcucha narzędzi Rust) wygenerowany moduł JavaScript glue eksportuje funkcje bezpośrednio i zapewnia właściwą konwersję typów. Można wywoływać je jak zwykłe funkcje JavaScript, używając typów zdefiniowanych w kodzie źródłowym Rust.

Funkcje WASM należy wywoływać z obsługi zdarzeń Reacta tak jak każdą funkcję synchroniczną: function handleClick() { const result = wasmInstance.current.processImage(imageData); setResult(result); }. Wywołania funkcji WASM są synchroniczne — blokują wątek wywołujący do czasu zakończenia obliczeń. To kolejny powód, aby w przypadku długotrwałych operacji uruchamiać je w Workerze.

Inicjalizacja WASM może się nie powieść: pobieranie może zakończyć się błędem, moduł może być niezgodny albo przeglądarce może brakować wymaganej funkcji. Komponenty zależne od WASM należy opakować w komponent React Error Boundary, aby przechwytywać błędy inicjalizacji i wyświetlać zawartość zastępczą. Błąd należy zapisać w logach na potrzeby debugowania oraz, jeśli to możliwe, zapewnić łagodne przejście do trybu ograniczonej funkcjonalności.

Vite wymaga dwóch wtyczek do prawidłowej obsługi modułów WASM: vite-plugin-wasm obsługuje importowanie plików WASM, a vite-plugin-top-level-await umożliwia używanie top-level await przez niektóry kod glue WASM. Obie wtyczki należy zainstalować i dodać do tablicy plugins w pliku vite.config.ts.

W projektach webpack należy włączyć eksperyment asyncWebAssembly w pliku webpack.config.js: experiments: { asyncWebAssembly: true }. Umożliwia to używanie import() do importowania plików WASM, które przeglądarka ładuje asynchronicznie. Projekty Create React App wymagają wykonania eject albo użycia CRACO w celu dodania tej konfiguracji.

Jaka jest przewaga WebAssembly.instantiateStreaming() nad WebAssembly.instantiate()?

WASM należy ładować za pomocą WebAssembly.instantiateStreaming(fetch(url)) lub dynamicznego importu w useEffect. Instancję należy przechowywać w useRef albo singletonie modułu. Podczas inicjalizacji trwającej 100–500 ms należy wyświetlać stan ładowania. Eksporty są dostępne za pośrednictwem instance.exports.fn(). Do obsługi błędów inicjalizacji należy używać Error Boundaries. Vite należy skonfigurować z użyciem vite-plugin-wasm i vite-plugin-top-level-await.