esbuild-plugin-wat

0.2.7 verified Fri May 01 auth: no javascript

esbuild plugin (v0.2.7) for importing WebAssembly (.wasm) and WebAssembly text format (.wat) files. Resolves imports to a default Uint8Array export suitable for WebAssembly.instantiate()/compile(). Ships TypeScript types. Differentiators: supports .wat compilation via wabt.js with caching, optional binaryen inlining optimization, configurable loader (binary/base64/file), experimental bundling of multiple wat/wasm files using import syntax. Lightweight alternative to full-featured bundler plugins like wasm-pack.

Common errors

error Cannot find module 'esbuild-plugin-wat' ↓

cause Package is ESM-only; require() fails in CJS context.

fix

Use import statement or set { "type": "module" } in package.json.

error Error: esbuild plugin 'wat' must be a function or an object with a name property ↓

cause Calling watPlugin incorrectly, e.g., watPlugin without parentheses.

fix

Use watPlugin() (a function call) in plugins array, not just watPlugin reference.

error TypeError: WebAssembly.instantiate: first argument must be a BufferSource or WebAssembly.Module ↓

cause Passing a string (e.g., base64) instead of Uint8Array to instantiate.

fix

Ensure the default export is used as-is: const wasm = await import('./file.wat'); WebAssembly.instantiate(wasm.default);

Warnings

gotcha Default export is a Uint8Array, not a compiled WebAssembly.Module. Must call WebAssembly.instantiate()/compile() explicitly. ↓

fix Use: const { instance } = await WebAssembly.instantiate(wasm);

deprecated Setting loader to 'file' may cause runtime fetch errors if the .wasm file path is not correctly resolved in production builds. ↓

fix Use 'binary' (default) to inline the binary; use 'file' only if you control the static file serving and path resolution.

breaking v0.2.0 dropped support for CommonJS require. package.json type field changed to 'module'. ↓

fix Switch to ESM imports: import watPlugin from 'esbuild-plugin-wat'

deprecated Options object is mutable and shared across builds; avoid reusing same config object for multiple esbuild runs. ↓

fix Create a fresh options object per build call: watPlugin({ ... })

gotcha Bundling (bundle: true) is experimental and does not support all wasm import syntaxes. ↓

fix Test thoroughly with your .wat files; fall back to multiple separate .wasm imports if issues arise.

Install

npm install esbuild-plugin-wat

yarn add esbuild-plugin-wat

pnpm add esbuild-plugin-wat

Imports

default

wrong

const watPlugin = require('esbuild-plugin-wat')

correct

import watPlugin from 'esbuild-plugin-wat'

Package is ESM-only; default export is a function, not an object.

WatPlugin

wrong

import { WatPlugin } from 'esbuild-plugin-wat'

correct

import type { WatPlugin } from 'esbuild-plugin-wat'

Type import only; WatPlugin is an interface, not a runtime value.

PluginOptions

wrong

import { PluginOptions } from 'esbuild-plugin-wat'

correct

import type { PluginOptions } from 'esbuild-plugin-wat'

Type import for configuration object shape.

Quickstart

Demonstrates esbuild configuration with watPlugin to import .wat files as Uint8Array, showing default options and commented alternatives.

import { build } from 'esbuild';
import watPlugin from 'esbuild-plugin-wat';

await build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/out.js',
  plugins: [watPlugin({
    loader: 'binary', // default: inline .wasm as binary
    // loader: 'file',  // emit separate .wasm files
    inlineFunctions: false,
    wasmFeatures: { simd: true },
    // bundle: true, // experimental bundling of wat modules
  })],
});

// In your source:
// import wasm from './example.wat';
// const module = await WebAssembly.instantiate(wasm);