Загрузка модулей WASM в React

Стандартный для браузера способ загрузить модуль WASM — WebAssembly.instantiateStreaming(fetch(url), importObject). Этот способ потоково загружает двоичный файл WASM по мере скачивания, немедленно начинает компиляцию и возвращает объект, содержащий модуль и экземпляр. Это наиболее эффективный способ загрузки в продуктивных системах.

Сборщики, такие как Vite и webpack, поддерживают импорт файлов WASM как модулей ES с помощью синтаксиса динамического импорта: import('./module.wasm'). Сборщик берёт на себя механизм загрузки. Такой подход естественно интегрируется с разделением кода: модуль WASM загружается только при выполнении импортирующего кода.

Загрузка модуля WASM — это асинхронная операция, которую следует выполнять в хуке useEffect. Получите и инициализируйте модуль внутри эффекта, сохраните экспортированные функции в состоянии или ссылке и обновите компонент после завершения инициализации. Пустой массив зависимостей гарантирует, что модуль будет загружен только один раз при монтировании компонента.

Храните экземпляр WASM в useRef, чтобы избежать повторной отрисовки при инициализации, или в переменной уровня модуля, если экземпляр является единым объектом, общим для всего приложения. Хранение в useState работает, но вызывает дополнительную повторную отрисовку, когда экземпляр становится доступен, — для простых случаев это приемлемо.

Для компонентов, которым необходим модуль WASM, оберните компонент в React.lazy и отрисовывайте его внутри границы Suspense. Модуль WASM можно загружать в рамках динамического импорта. Suspense показывает резервный скелет, пока модуль инициализируется, обеспечивая удобный процесс загрузки.

Загрузка и инициализация модулей WASM обычно занимают 100–500 мс при типичном подключении, в зависимости от размера модуля и скорости устройства. Всегда показывайте индикатор загрузки (скелетон, индикатор вращения или индикатор выполнения), пока продолжается инициализация. Блокировка интерфейса во время инициализации WASM без визуальной обратной связи создаёт ощущение зависания.

После инициализации функции WASM доступны через instance.exports.myFunction(). При использовании wasm-bindgen (инструментов Rust) сгенерированный связующий модуль JavaScript напрямую экспортирует функции с корректным приведением типов. Вызывайте их как обычные функции JavaScript, используя типы, определённые в исходном коде Rust.

Вызывайте функции WASM из обработчиков событий React так же, как любую синхронную функцию: function handleClick() { const result = wasmInstance.current.processImage(imageData); setResult(result); }. Вызовы функций WASM являются синхронными: они блокируют вызывающий поток до завершения вычислений. Это ещё одна причина выполнять длительные операции в веб-воркере.

Инициализация WASM может завершиться с ошибкой: получение файла может не удаться, модуль может оказаться несовместимым или в браузере может отсутствовать необходимая функция. Оберните зависящие от WASM компоненты в границу обработки ошибок React, чтобы перехватывать сбои и показывать резервный интерфейс. Записывайте ошибку в журнал для отладки и, если возможно, предусмотрите плавный переход к упрощённому режиму работы.

Vite требует два плагина для корректной работы с модулями WASM: vite-plugin-wasm обрабатывает импорт файлов WASM, а vite-plugin-top-level-await включает ожидание на верхнем уровне, используемое некоторым связующим кодом WASM. Установите оба плагина и добавьте их в массив plugins в файле vite.config.ts.

В проектах webpack включите эксперимент asyncWebAssembly в файле webpack.config.js: experiments: { asyncWebAssembly: true }. Это позволяет импортировать файлы WASM с помощью import(), при этом браузер загружает модуль асинхронно. Для проектов Create React App требуется извлечь конфигурацию или использовать CRACO, чтобы добавить эту настройку.

В чём преимущество WebAssembly.instantiateStreaming() перед WebAssembly.instantiate()?

Загружайте WASM с помощью WebAssembly.instantiateStreaming(fetch(url)) или динамического импорта в useEffect. Храните экземпляр в useRef или в едином экземпляре модуля. Показывайте состояние загрузки во время инициализации, занимающей 100–500 мс. Получайте экспортированные функции через instance.exports.fn(). Используйте границы обработки ошибок для сбоев инициализации. Настройте Vite с помощью vite-plugin-wasm и vite-plugin-top-level-await.