Carga de módulos WASM en React

La forma estándar del navegador de cargar un módulo WASM es WebAssembly.instantiateStreaming(fetch(url), importObject). Este método transmite el binario WASM mientras se descarga, inicia la compilación de inmediato y se resuelve con un objeto que contiene el módulo y la instancia. Es el método de carga más eficiente para uso en producción.

Los bundlers como Vite y webpack permiten importar archivos WASM como módulos ES mediante la sintaxis de importación dinámica: import('./module.wasm'). El bundler se encarga de los mecanismos de carga. Este enfoque se integra de forma natural con el code-splitting: el módulo WASM solo se carga cuando se ejecuta el código que lo importa.

Cargar un módulo WASM es una operación asíncrona que debe realizarse en un hook useEffect. Obtenga e instancie el módulo dentro del efecto, almacene las funciones exportadas en el estado o en una ref y actualice el componente cuando finalice la inicialización. La matriz de dependencias vacía garantiza que el módulo se cargue una sola vez por cada montaje del componente.

Almacene la instancia de WASM en un useRef para evitar nuevos renderizados durante la inicialización, o en una variable a nivel de módulo si la instancia es un singleton compartido por toda la aplicación. Almacenarla en useState también funciona, pero provoca un nuevo renderizado adicional cuando la instancia está disponible; esto es aceptable en casos sencillos.

Para los componentes que necesitan un módulo WASM para funcionar, envuelva el componente en React.lazy y muéstrelo dentro de un límite de Suspense. El módulo WASM puede cargarse como parte de la importación dinámica. Suspense muestra un esqueleto alternativo mientras se inicializa el módulo, lo que proporciona una experiencia de carga fluida.

Los módulos WASM tardan entre 100 y 500 ms en cargarse e inicializarse con una conexión habitual, según el tamaño del módulo y la velocidad del dispositivo. Muestre siempre un indicador de carga (esqueleto, spinner o barra de progreso) mientras la inicialización esté en curso. Bloquear la interfaz durante la inicialización de WASM sin ofrecer una indicación visual crea la percepción de que la aplicación se ha quedado bloqueada.

Después de la instanciación, las funciones de WASM están disponibles mediante instance.exports.myFunction(). Al utilizar wasm-bindgen (la cadena de herramientas de Rust), el módulo auxiliar de JavaScript generado exporta directamente las funciones con la conversión de tipos adecuada. Puede llamarlas como funciones normales de JavaScript utilizando los tipos definidos en el código fuente de Rust.

Llame a las funciones de WASM desde los controladores de eventos de React como lo haría con cualquier llamada de función síncrona: function handleClick() { const result = wasmInstance.current.processImage(imageData); setResult(result); }. Las llamadas a funciones de WASM son síncronas: bloquean el hilo que las realiza hasta que finaliza el cálculo, otra razón para ejecutarlas en un Worker cuando se trate de operaciones prolongadas.

La inicialización de WASM puede fallar: la obtención puede fallar, el módulo puede ser incompatible o el navegador puede no disponer de alguna función necesaria. Envuelva los componentes que dependan de WASM en un Error Boundary de React para capturar los fallos de inicialización y mostrar un contenido alternativo. Registre el error para facilitar la depuración y, si es posible, proporcione una vía de degradación controlada.

Vite requiere dos plugins para gestionar correctamente los módulos WASM: vite-plugin-wasm gestiona las importaciones de archivos WASM y vite-plugin-top-level-await habilita el await de nivel superior que utiliza parte del código auxiliar de WASM. Instale ambos y añádalos a la matriz plugins de vite.config.ts.

En proyectos de webpack, habilite el experimento asyncWebAssembly en webpack.config.js: experiments: { asyncWebAssembly: true }. Esto permite usar import() con archivos WASM y que el navegador cargue el módulo de forma asíncrona. Los proyectos de Create React App requieren hacer eject o utilizar CRACO para añadir esta configuración.

¿Qué ventaja ofrece WebAssembly.instantiateStreaming() frente a WebAssembly.instantiate()?

Cargue WASM con WebAssembly.instantiateStreaming(fetch(url)) o mediante una importación dinámica en useEffect. Almacene la instancia en useRef o en un singleton de módulo. Muestre el estado de carga durante la inicialización, que tarda entre 100 y 500 ms. Acceda a las exportaciones mediante instance.exports.fn(). Utilice Error Boundaries para los fallos de inicialización. Configure Vite con vite-plugin-wasm y vite-plugin-top-level-await.