Charger des modules WASM dans React

La manière standard de charger un module WASM dans le navigateur est WebAssembly.instantiateStreaming(fetch(url), importObject). Cette méthode diffuse le code binaire WASM au fur et à mesure de son téléchargement, commence immédiatement la compilation et se résout en un objet contenant le module et l'instance. Il s'agit de la méthode de chargement la plus efficace pour une utilisation en production.

Les outils de regroupement comme Vite et webpack prennent en charge l'importation de fichiers WASM en tant que modules ES à l'aide de la syntaxe d'importation dynamique : import('./module.wasm'). L'outil de regroupement prend en charge les mécanismes de chargement. Cette approche s'intègre naturellement au découpage du code : le module WASM est chargé uniquement lorsque le code qui l'importe s'exécute.

Le chargement d'un module WASM est une opération asynchrone qui doit être effectuée dans un crochet useEffect. Récupérez et instanciez le module dans l'effet, stockez les fonctions exportées dans l'état ou dans une référence, puis mettez à jour le composant lorsque l'initialisation est terminée. Le tableau de dépendances vide garantit que le module ne sera chargé qu'une seule fois par montage du composant.

Stockez l'instance WASM dans une référence useRef pour éviter de nouveaux rendus lors de l'initialisation, ou dans une variable au niveau du module si l'instance est unique et partagée dans toute l'application. La stocker dans useState fonctionne également, mais provoque un nouveau rendu supplémentaire lorsque l'instance devient disponible : c'est acceptable dans les cas simples.

Pour les composants qui nécessitent un module WASM pour fonctionner, enveloppez le composant dans React.lazy et affichez-le à l'intérieur d'une limite Suspense. Le module WASM peut être chargé dans le cadre de l'importation dynamique. Suspense affiche un squelette de repli pendant l'initialisation du module, ce qui offre une expérience de chargement claire.

Les modules WASM mettent généralement entre 100 et 500 ms à se charger et à s'instancier sur une connexion classique, selon la taille du module et la vitesse de l'appareil. Affichez toujours un indicateur de chargement (squelette, indicateur circulaire ou barre de progression) pendant l'initialisation. Bloquer l'interface utilisateur pendant l'initialisation de WASM sans fournir de retour visuel donne l'impression que l'application est bloquée.

Après l'instanciation, les fonctions WASM sont disponibles via instance.exports.myFunction(). Avec wasm-bindgen (la chaîne d'outils Rust), le module de liaison JavaScript généré exporte directement les fonctions avec une conversion correcte des types. Vous les appelez comme des fonctions JavaScript ordinaires, en utilisant les types définis dans le code source Rust.

Appelez les fonctions WASM depuis les gestionnaires d'événements React comme vous le feriez pour tout appel de fonction synchrone : function handleClick() { const result = wasmInstance.current.processImage(imageData); setResult(result); }. Les appels de fonctions WASM sont synchrones : ils bloquent le fil d'exécution appelant jusqu'à la fin du calcul, ce qui constitue une raison supplémentaire de les exécuter dans un fil d'exécution Web pour les opérations longues.

L'initialisation de WASM peut échouer : la récupération peut échouer, le module peut être incompatible ou le navigateur peut ne pas disposer d'une fonctionnalité nécessaire. Enveloppez les composants qui dépendent de WASM dans une limite d'erreur React afin d'intercepter les échecs d'initialisation et d'afficher une solution de repli. Consignez l'erreur à des fins de débogage et prévoyez si possible une solution de dégradation progressive.

Vite nécessite deux plug-ins pour gérer correctement les modules WASM : vite-plugin-wasm gère les importations de fichiers WASM et vite-plugin-top-level-await active l'attente au niveau supérieur utilisée par certains codes de liaison WASM. Installez les deux plug-ins et ajoutez-les au tableau plugins dans vite.config.ts.

Dans les projets webpack, activez l'expérience asyncWebAssembly dans webpack.config.js : experiments: { asyncWebAssembly: true }. Cela permet d'importer des fichiers WASM avec import(), le navigateur chargeant le module de manière asynchrone. Les projets Create React App nécessitent d'éjecter la configuration ou d'utiliser CRACO pour ajouter cette configuration.

Quel est l'avantage de WebAssembly.instantiateStreaming() par rapport à WebAssembly.instantiate() ?

Chargez WASM avec WebAssembly.instantiateStreaming(fetch(url)) ou par importation dynamique dans useEffect. Stockez l'instance dans useRef ou dans une instance unique au niveau du module. Affichez l'état de chargement pendant les 100 à 500 ms d'initialisation. Accédez aux exportations via instance.exports.fn(). Utilisez des limites d'erreur pour les échecs d'initialisation. Configurez Vite avec vite-plugin-wasm et vite-plugin-top-level-await.