{"id":22974,"library":"wasm-loader","title":"WebAssembly Binary Module Loader for Webpack","description":"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.","status":"maintenance","version":"1.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/ballercat/wasm-loader","tags":["javascript","wasm","webassembly","webpack","loader"],"install":[{"cmd":"npm install wasm-loader","lang":"bash","label":"npm"},{"cmd":"yarn add wasm-loader","lang":"bash","label":"yarn"},{"cmd":"pnpm add wasm-loader","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for optional dead code elimination feature (dce=1 query)","package":"wasm-dce","optional":true}],"imports":[{"note":"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>.","wrong":"const createInstance = require('./module.wasm')","symbol":"default (createInstance)","correct":"import createInstance from './module.wasm'"},{"note":"When using dead code elimination, you must explicitly list exported function names (e.g., &add) to keep; otherwise all exports may be removed.","wrong":"import createInstance from './module.wasm?dce=1'","symbol":"default with DCE","correct":"import createInstance from './module.wasm?dce=1&exportedFunc'"},{"note":"The loader passes the provided importsObject to WebAssembly.instantiate. Default imports only work for trivial modules.","wrong":"createInstance() without custom imports for modules that require specific importsObject","symbol":"default with custom imports","correct":"import createInstance from './module.wasm'; createInstance({ 'env': { 'memory': new WebAssembly.Memory({initial: 100}) } })"}],"quickstart":{"code":"// webpack.config.js\nmodule.exports = {\n  module: {\n    rules: [\n      { test: /\\.wasm$/, use: 'wasm-loader' }\n    ]\n  }\n};\n\n// app.js\nimport createInstance from './factorial.wasm';\n\ncreateInstance().then(instance => {\n  const factorial = instance.exports._Z4facti;\n  console.log(factorial(5)); // 120\n}).catch(err => console.error(err));","lang":"javascript","description":"Shows how to configure Webpack with wasm-loader and use the default export to instantiate a WebAssembly module and call an exported function."},"warnings":[{"fix":"Use '.then()' to access instance or await the promise.","message":"Loader returns a function returning Promise<WebAssembly.Instance>, not the instance directly.","severity":"breaking","affected_versions":">=1.0"},{"fix":"Pass custom import object to the loader function matching module expectations.","message":"Default importsObject may not satisfy complex Emscripten-compiled modules; custom imports required.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Test thoroughly and consider alternatives if DCE fails.","message":"Dead code elimination via ?dce=1 is experimental and may not work with all wasm features.","severity":"deprecated","affected_versions":">=1.3.0"},{"fix":"Consider separate loading strategies (e.g., dynamic import) for large wasm.","message":"wasm files become part of JS bundle, increasing bundle size; not suitable for large wasm modules.","severity":"gotcha","affected_versions":">=1.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Add { test: /\\.wasm$/, use: 'wasm-loader' } to module.rules in webpack.config.js.","cause":"Webpack missing wasm-loader rule for .wasm files.","error":"Module parse failed: Unexpected token (1:0)\nYou may need an appropriate loader to handle this file type."},{"fix":"Ensure webpack config applies wasm-loader to .wasm files and use correct import statement: import createInstance from './file.wasm'.","cause":"Default import not returning function; possibly using wrong import syntax or loader not applied.","error":"TypeError: createInstance is not a function"},{"fix":"Ensure importsObject argument is a plain object with appropriate properties (e.g., { env: { memory: ..., table: ... } }).","cause":"Passed null or non-object as importsObject to the loader function.","error":"Uncaught (in promise) LinkError: import object field 'env' is not an Object"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}