wasm-loader

library1.3.0jsnpmunverified

A Webpack loader that allows importing .wasm binary files directly into JavaScript bundles as constructor functions returning a Promise resolving to WebAssembly.Instance. Current stable version 1.3.0. It eliminates the need for manual fetch and instantiation, converting wasm bytes to Uint8Arrays embedded in the JS bundle. Differentiators include optional dead code elimination via `dce=1` query parameter and support for passing custom import objects. Requires Webpack and Node.js, with peer dependency on wasm-dce. Suitable for basic wasm modules; for complex Emscripten output, custom imports are necessary.

devops

npm install wasm-loader

github ↗package ↗

INSTALL

IMPORT

SIG · WASM-LOADER

wasm-loader

devopsjavascriptv1.3.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.

default (createInstance)

✓ import createInstance from './module.wasm'

✗ const createInstance = require('./module.wasm')

ESM import is the primary use; CommonJS require works but may not resolve correctly with all Webpack configurations. The default export is a function returning Promise<WebAssembly.Instance>.

default with DCE

✓ import createInstance from './module.wasm?dce=1&exportedFunc'

✗ import createInstance from './module.wasm?dce=1'

When using dead code elimination, you must explicitly list exported function names (e.g., &add) to keep; otherwise all exports may be removed.

default with custom imports

✓ import createInstance from './module.wasm'; createInstance({ 'env': { 'memory': new WebAssembly.Memory({initial: 100}) } })

✗ createInstance() without custom imports for modules that require specific importsObject

The loader passes the provided importsObject to WebAssembly.instantiate. Default imports only work for trivial modules.

Shows how to configure Webpack with wasm-loader and use the default export to instantiate a WebAssembly module and call an exported function.

// webpack.config.js module.exports = { module: { rules: [ { test: /\.wasm$/, use: 'wasm-loader' } ] } }; // app.js import createInstance from './factorial.wasm'; createInstance().then(instance => { const factorial = instance.exports._Z4facti; console.log(factorial(5)); // 120 }).catch(err => console.error(err));

Debug

Known issues

breakingLoader returns a function returning Promise<WebAssembly.Instance>, not the instance directly.

fix

Use '.then()' to access instance or await the promise.

affects: >=1.0

gotchaDefault importsObject may not satisfy complex Emscripten-compiled modules; custom imports required.

fix

Pass custom import object to the loader function matching module expectations.

affects: >=1.0

deprecatedDead code elimination via ?dce=1 is experimental and may not work with all wasm features.

fix

Test thoroughly and consider alternatives if DCE fails.

affects: >=1.3.0

gotchawasm files become part of JS bundle, increasing bundle size; not suitable for large wasm modules.

fix

Consider separate loading strategies (e.g., dynamic import) for large wasm.

affects: >=1.0

Errors

Common errors & fixes

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

Webpack missing wasm-loader rule for .wasm files.

fix

Add { test: /\.wasm$/, use: 'wasm-loader' } to module.rules in webpack.config.js.

TypeError: createInstance is not a function

Default import not returning function; possibly using wrong import syntax or loader not applied.

fix

Ensure webpack config applies wasm-loader to .wasm files and use correct import statement: import createInstance from './file.wasm'.

Uncaught (in promise) LinkError: import object field 'env' is not an Object

Passed null or non-object as importsObject to the loader function.

fix

Ensure importsObject argument is a plain object with appropriate properties (e.g., { env: { memory: ..., table: ... } }).

Upgrade

Version history

1.3.0latest on npm

Audit

Dependencies

wasm-dceoptionalRequired for optional dead code elimination feature (dce=1 query)

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/ballercat/wasm-loader ↗

packagehttps://www.npmjs.com/package/wasm-loader ↗