Vite Plugin WASM

3.6.0 verified Mon Apr 27 auth: no javascript

Adds WebAssembly ESM integration (aka Webpack's asyncWebAssembly) to Vite and supports wasm-pack generated modules. Current stable version is 3.6.0, compatible with Vite 2.x through 8.x. Releases follow regular cadence with breaking changes aligned with Vite major versions. Key differentiators: enables importing .wasm files as ES modules, handles wasm-pack output, and works in Web Workers. Requires vite-plugin-top-level-await for browser targets below esnext. Ships TypeScript declarations.

Common errors

error No loader is configured for ".wasm" files: node_modules/somepackage/somefile.wasm ↓

cause Vite version below 3.0.3 or plugin version below 3.1.0 does not handle WASM imports from node_modules.

fix

Upgrade Vite to >=3.0.3 or plugin to >=3.1.0, or add 'optimizeDeps.exclude: ["somepackage"]' to vite.config.

error Top-level await is not available in the configured target environment ↓

cause Omitting vite-plugin-top-level-await when build.target is not 'esnext'.

fix

Add topLevelAwait() plugin to Vite config.

error Cannot find module 'vite-plugin-wasm' when using require() ↓

cause Package is ESM-only; require() is not supported.

fix

Use import or dynamic import() instead of require().

Warnings

gotcha TypeScript typing is broken: importing .wasm files still gets Vite's built-in typing, not the plugin's custom module declaration. ↓

fix Use asterisk import (import * as wasmModule from './module.wasm') with type assertion.

breaking ESBuild errors with .wasm files in Vite < 3.0.3: 'No loader is configured for ".wasm" files' appears when importing WASM from node_modules. ↓

fix Upgrade Vite to >=3.0.3 or plugin to >=3.1.0, or exclude the offending package from optimizeDeps.

gotcha Web Workers require manual addition of plugin to worker.plugins. ↓

fix Add wasm() and topLevelAwait() to worker.plugins in Vite config, and don't set worker.format to 'es' for Firefox support.

deprecated worker.format: 'es' support removed in vite-plugin-top-level-await >= 1.3.0; leaving format default (module) is fine. ↓

fix Remove worker.format configuration; rely on vite-plugin-top-level-await for compatibility.

Install

npm install vite-plugin-wasm

yarn add vite-plugin-wasm

pnpm add vite-plugin-wasm

Imports

default

wrong

const wasm = require('vite-plugin-wasm')

correct

import wasm from 'vite-plugin-wasm'

ESM-only package; use dynamic import for CommonJS

wasm
wrong
```
import { wasm } from 'vite-plugin-wasm'
```
correct
```
import wasm from 'vite-plugin-wasm'
```
Default export, not named. Plugin function is the default export.

VitePluginWasmOptions

wrong

import { VitePluginWasmOptions } from 'vite-plugin-wasm'

correct

import type { VitePluginWasmOptions } from 'vite-plugin-wasm'

TypeScript only; use type import to avoid runtime issues

Quickstart

Shows basic setup with required companion plugin for top-level await support.

import wasm from 'vite-plugin-wasm';
import topLevelAwait from 'vite-plugin-top-level-await';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    wasm(),
    topLevelAwait()
  ]
});