Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–223 runs
build_error
glibcnode 18–223 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
default
✓ import wasm from 'vite-plugin-wasm'
✗ const wasm = require('vite-plugin-wasm')
ESM-only package; use dynamic import for CommonJS
wasm
✓ import wasm from 'vite-plugin-wasm'
✗ import { wasm } from 'vite-plugin-wasm'
Default export, not named. Plugin function is the default export.
VitePluginWasmOptions
✓ import type { VitePluginWasmOptions } from 'vite-plugin-wasm'
✗ import { VitePluginWasmOptions } from 'vite-plugin-wasm'
TypeScript only; use type import to avoid runtime issues
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()
]
});
Debug
Known issues
gotchaTypeScript typing is broken: importing .wasm files still gets Vite's built-in typing, not the plugin's custom module declaration.fixUse asterisk import (import * as wasmModule from './module.wasm') with type assertion.
affects: >=0.0.0
breakingESBuild errors with .wasm files in Vite < 3.0.3: 'No loader is configured for ".wasm" files' appears when importing WASM from node_modules.fixUpgrade Vite to >=3.0.3 or plugin to >=3.1.0, or exclude the offending package from optimizeDeps.
affects: <3.1.0
gotchaWeb Workers require manual addition of plugin to worker.plugins.fixAdd wasm() and topLevelAwait() to worker.plugins in Vite config, and don't set worker.format to 'es' for Firefox support.
affects: >=0.0.0
deprecatedworker.format: 'es' support removed in vite-plugin-top-level-await >= 1.3.0; leaving format default (module) is fine.fixRemove worker.format configuration; rely on vite-plugin-top-level-await for compatibility.
affects: >=1.3.0 of vite-plugin-top-level-await
Errors
Common errors & fixes
No loader is configured for ".wasm" files: node_modules/somepackage/somefile.wasm
Vite version below 3.0.3 or plugin version below 3.1.0 does not handle WASM imports from node_modules.
fixUpgrade Vite to >=3.0.3 or plugin to >=3.1.0, or add 'optimizeDeps.exclude: ["somepackage"]' to vite.config.
Top-level await is not available in the configured target environment
Omitting vite-plugin-top-level-await when build.target is not 'esnext'.
fixAdd topLevelAwait() plugin to Vite config.
Cannot find module 'vite-plugin-wasm' when using require()
Package is ESM-only; require() is not supported.
fixUse import or dynamic import() instead of require().
Audit
Dependencies
viterequiredpeer dependency; plugin works with Vite 2.x to 8.x
vite-plugin-top-level-awaitoptionalrecommended companion plugin for non-esnext build targets to handle top-level await in WASM modules