Carregando módulos WASM no React

A maneira padrão do navegador de carregar um módulo WASM é WebAssembly.instantiateStreaming(fetch(url), importObject). Ela transmite o binário WASM à medida que ele é baixado, inicia a compilação imediatamente e resolve com um objeto que contém o módulo e a instância. É o método de carregamento mais eficiente para uso em produção.

Empacotadores como Vite e webpack oferecem suporte à importação de arquivos WASM como módulos ES usando a sintaxe de importação dinâmica: import('./module.wasm'). O empacotador gerencia o processo de carregamento. Essa abordagem se integra naturalmente à divisão de código — o módulo WASM é carregado somente quando o código que o importa é executado.

Carregar um módulo WASM é uma operação assíncrona que deve ficar em um gancho useEffect. Busque e instancie o módulo dentro do efeito, armazene as funções exportadas no estado ou em uma referência e atualize o componente quando a inicialização for concluída. A lista de dependências vazia garante que o módulo seja carregado apenas uma vez por montagem do componente.

Armazene a instância do WASM em um useRef para evitar novas renderizações durante a inicialização ou em uma variável no nível do módulo se a instância for única e compartilhada por toda a aplicação. Armazená-la em useState funciona, mas causa uma nova renderização adicional quando a instância fica disponível — algo aceitável em casos simples.

Para componentes que precisam de um módulo WASM para funcionar, envolva o componente em React.lazy e renderize-o dentro de um limite de Suspense. O módulo WASM pode ser carregado como parte da importação dinâmica. Suspense exibe um esqueleto de carregamento alternativo enquanto o módulo é inicializado, proporcionando uma experiência de carregamento fluida.

Os módulos WASM levam de 100 a 500 ms para carregar e ser instanciados em uma conexão comum, dependendo do tamanho do módulo e da velocidade do dispositivo. Sempre mostre um indicador de carregamento (esqueleto, indicador giratório ou barra de progresso) enquanto a inicialização estiver em andamento. Bloquear a interface durante a inicialização do WASM sem fornecer um retorno visual cria a percepção de travamento.

Após a instanciação, as funções WASM ficam disponíveis por meio de instance.exports.myFunction(). Ao usar wasm-bindgen (a cadeia de ferramentas do Rust), o módulo de integração JavaScript gerado exporta as funções diretamente, com conversão adequada de tipos. Você as chama como funções JavaScript comuns, usando os tipos definidos no código-fonte Rust.

Chame funções WASM a partir de manipuladores de eventos do React como qualquer chamada de função síncrona: function handleClick() { const result = wasmInstance.current.processImage(imageData); setResult(result); }. As chamadas de funções WASM são síncronas — elas bloqueiam a linha de execução que faz a chamada até que o cálculo seja concluído, o que é outro motivo para executá-las em um processo em segundo plano para operações longas.

A inicialização do WASM pode falhar: a busca pode falhar, o módulo pode ser incompatível ou o navegador pode não ter determinado recurso. Envolva os componentes que dependem do WASM em um limite de erros do React para capturar falhas de inicialização e exibir uma alternativa visual. Registre o erro para depuração e forneça, se possível, um caminho de degradação adequada.

O Vite exige dois plugins para lidar corretamente com módulos WASM: vite-plugin-wasm gerencia as importações de arquivos WASM e vite-plugin-top-level-await habilita o await no nível superior usado por parte do código de integração do WASM. Instale ambos e adicione-os à matriz plugins em vite.config.ts.

Em projetos webpack, ative o experimento asyncWebAssembly em webpack.config.js: experiments: { asyncWebAssembly: true }. Isso permite a import() de arquivos WASM, com o navegador carregando o módulo de forma assíncrona. Projetos do Create React App exigem a ejeção ou o uso do CRACO para adicionar essa configuração.

Qual é a vantagem de WebAssembly.instantiateStreaming() em relação a WebAssembly.instantiate()?

Carregue WASM com WebAssembly.instantiateStreaming(fetch(url)) ou com uma importação dinâmica em useEffect. Armazene a instância em useRef ou em uma instância única do módulo. Mostre o estado de carregamento durante a inicialização de 100 a 500 ms. Acesse as exportações por meio de instance.exports.fn(). Use limites de erro para falhas de inicialização. Configure o Vite com vite-plugin-wasm e vite-plugin-top-level-await.