Registry / serialization / esbuild-plugin-wasm

esbuild-plugin-wasm

library1.1.0jsnpmunverified

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.

serialization http-networking web-framework

npm install esbuild-plugin-wasm

github ↗package ↗

INSTALL

IMPORT

SIG · ESBUILD-PLUGIN-WAS

esbuild-plugin-wasm

serializationjavascriptv1.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

wasmLoader

✓ import { wasmLoader } from 'esbuild-plugin-wasm'

✗ import wasmLoader from 'esbuild-plugin-wasm'

The library ships only a named export 'wasmLoader'. Default import is incorrect.

wasmLoader

✓ const { wasmLoader } = require('esbuild-plugin-wasm')

✗ 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

✓ import wasm from './lib.wasm'

✗ const wasm = require('./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.

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));

Debug

Known issues

breakingTop-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.

affects: >=0.0.0

gotchaIn 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.

affects: >=0.0.0

gotchaEmbedded 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.

affects: >=0.0.0

deprecatedThe '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').

affects: >=0.0.0

Errors

Common errors & fixes

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

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

fix

Set format: 'esm' in your esbuild config.

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

The plugin is not registered in the esbuild plugins array.

fix

Add wasmLoader() to the plugins list.

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

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.

Upgrade

Version history

1.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

10 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/Tschrock/esbuild-plugin-wasm ↗

packagehttps://www.npmjs.com/package/esbuild-plugin-wasm ↗