esbuild-plugin-wasm

1.1.0 verified Mon Apr 27 auth: no javascript

An asynchronous .wasm file loader for esbuild that lets you import WebAssembly modules directly via import statements, following the WebAssembly/ES Module Integration proposal. Current stable version is 1.1.0. It supports two modes: 'deferred' (default, copies WASM binary to output and fetches at runtime) and 'embedded' (embeds as base64, increasing bundle size ~30%). Requires esbuild >=0.11.0 and Node >=10.0.0. Key differentiator: lightweight alternative to heavier bundler setups, but note that top-level await only works with 'esm' output format, not 'iife' or 'cjs'. Ships TypeScript definitions.

Common errors

error Error: Top-level await is not supported in this output format (cjs/iife) ↓

cause Using output format 'cjs' or 'iife' with esbuild-plugin-wasm, which requires 'esm'.

fix

Set format: 'esm' in your esbuild config.

error Error: Could not resolve .../lib.wasm (maybe use the wasmLoader plugin?) ↓

cause The plugin is not registered in the esbuild plugins array.

fix

Add wasmLoader() to the plugins list.

error SyntaxError: Unexpected token 'export' (or similar parse error) when importing .wasm in Node.js without esbuild ↓

cause Trying to import a .wasm file directly without a bundler like esbuild that provides the loader.

fix

Use esbuild with the wasmLoader plugin to bundle the .wasm file.

Warnings

breaking Top-level await is required but esbuild only supports it with 'esm' output format. Using 'iife' or 'cjs' will cause an error. ↓

fix Set format: 'esm' in esbuild build options, or use deferred mode and ensure runtime supports fetch.

gotcha In deferred mode, the WASM binary is not bundled; it must be served alongside the output JavaScript. If missing, fetch will fail at runtime. ↓

fix Deploy the .wasm file to the same directory as the output JS, or adjust paths with 'publicPath' or similar.

gotcha Embedded mode increases bundle size by ~30% due to base64 encoding. This may cause performance issues for large WASM files. ↓

fix Use deferred mode for production, or compress WASM before embedding.

deprecated The 'require' syntax for importing .wasm files may not work with some esbuild versions or configurations. The plugin is designed for ESM imports. ↓

fix Switch to ESM import syntax (e.g., import wasm from './lib.wasm').

Install

npm install esbuild-plugin-wasm

yarn add esbuild-plugin-wasm

pnpm add esbuild-plugin-wasm

Imports

wasmLoader
wrong
```
import wasmLoader from 'esbuild-plugin-wasm'
```
correct
```
import { wasmLoader } from 'esbuild-plugin-wasm'
```
The library ships only a named export 'wasmLoader'. Default import is incorrect.
wasmLoader
wrong
```
const wasmLoader = require('esbuild-plugin-wasm')
```
correct
```
const { wasmLoader } = require('esbuild-plugin-wasm')
```
Using the module with CommonJS (require) works, but the default export is not a function; only destructuring works.
wasm module
wrong
```
const wasm = require('./lib.wasm')
```
correct
```
import wasm from './lib.wasm'
```
For CommonJS, you can still use require to import .wasm files after the plugin is set up, but it's not recommended. The ESM-style import is the intended usage.
type for wasm
```
import wasm from './lib.wasm'; const module: typeof wasm = wasm
```
TypeScript users may need a type declaration for .wasm imports. This plugin exports types via the plugin itself, but explicit declarations might be needed depending on project setup.

Quickstart

Shows basic usage: set up esbuild with the wasm plugin in ESM mode, then import a .wasm file.

// build.js
import esbuild from 'esbuild';
import { wasmLoader } from 'esbuild-plugin-wasm';

await esbuild.build({
  entryPoints: ['app.js'],
  bundle: true,
  outdir: 'out',
  format: 'esm',
  plugins: [wasmLoader({ mode: 'deferred' })],
});

// app.js
import wasm from './lib.wasm';
console.log(wasm.add(1, 2));