wast-loader

1.14.1 verified Sat Apr 25 auth: no javascript maintenance

Webpack loader for WebAssembly text format (.wast/.wat files). Version 1.14.1 compiles WAT to binary WebAssembly modules during webpack bundling. The loader integrates with webpack's webassembly/experimental module type (webpack 4) and is part of the webassemblyjs toolchain. It has limited ongoing development; the webassemblyjs monorepo appears in maintenance mode. Key differentiator: enables writing WebAssembly in text format directly in webpack projects without separate compilation steps.

Common errors

error Module parse failed: Unexpected token (1:0) You may need an appropriate loader to handle this file type. ↓

cause Missing type: 'webassembly/experimental' in webpack rule or loader not configured; webpack treats .wast as a regular file.

fix

Ensure rule has loader: 'wast-loader' and type: 'webassembly/experimental' in webpack 4.

error Error: Cannot find module '@webassemblyjs/ast' ↓

cause Missing peer dependency; wast-loader requires @webassemblyjs packages that are not automatically installed.

fix

Run: npm install @webassemblyjs/ast @webassemblyjs/wast-parser @webassemblyjs/wast-printer @webassemblyjs/helper-wasm-bytecode

error TypeError: wasmModule.instance is undefined ↓

cause The loader returns a Module object that may not have an instance if used incorrectly (e.g., accessing .instance before the promise resolves).

fix

Use wasmModule.then(module => { const instance = module.instance; ... }) or await wasmModule.

Warnings

gotcha Webpack 5 no longer supports webassembly/experimental; migrate to experiments: { asyncWebAssembly: true } and use asset/resource or async modules. ↓

fix Upgrade to webpack 5 and use experiments.asyncWebAssembly, or use a newer loader like wasm-loader.

deprecated The package is part of the webassemblyjs monorepo, which is in maintenance mode. No new features are expected. ↓

fix Consider using native webpack 5 wasm support or alternative loaders like wasm-pack.

gotcha Default webpack 4 config requires type: 'webassembly/experimental' or the loader may silently fail without warning. ↓

fix Add 'type': 'webassembly/experimental' to the rule.

gotcha Output is a Module object, not a buffer. Access .instance for the WebAssembly.Instance. ↓

fix Use wasmModule.instance.then(instance => { ... }).

Install

npm install wast-loader

yarn add wast-loader

pnpm add wast-loader

Imports

wast-loader (webpack rule)

wrong

module.exports = { module: { rules: [{ test: /\.wast$/, loader: 'wast-loader' }] } };

correct

module.exports = { module: { rules: [{ test: /\.wast$/, loader: 'wast-loader', type: 'webassembly/experimental' }] } };

Webpack 4 requires type: 'webassembly/experimental' for webassembly modules. Omitting it will cause errors.

CommonJS require
wrong
```
import wasm from './module.wast';
```
correct
```
const wasm = require('./module.wast');
```
This is a webpack loader, so the import style depends on webpack config. The loader output is a wasm module object.
ESM import
wrong
```
const wasm = require('./module.wast');
```
correct
```
import wasm from './module.wast';
```
If using webpack with type: 'module', ESM imports are preferred. The default export is the wasm module.
TypeScript type import
wrong
```
import WasmModule from './module.wast';
```
correct
```
import type WasmModule from './module.wast';
```
For type-only imports to avoid bundling issues. Requires a type declaration for .wast files.

Quickstart

Shows a minimal webpack 4 config using wast-loader with .wast files, a simple add.wat module, and usage in entry point.

// webpack.config.js
const path = require('path');

module.exports = {
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js',
  },
  module: {
    rules: [
      {
        test: /\.wast$/,
        loader: 'wast-loader',
        type: 'webassembly/experimental',
      },
    ],
  },
};

// src/add.wat
(module
  (func (export "add") (param $a i32) (param $b i32) (result i32)
    local.get $a
    local.get $b
    i32.add
  )
)

// src/index.js
import wasmModule from './add.wast';

wasmModule.instance.then(instance => {
  const { add } = instance.exports;
  console.log(add(2, 3)); // 5
});