{"id":21287,"library":"esbuild-plugin-wasm","title":"esbuild-plugin-wasm","description":"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.","status":"active","version":"1.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/Tschrock/esbuild-plugin-wasm","tags":["javascript","wasm","webassembly","esbuild","plugin","esbuild-plugin","typescript"],"install":[{"cmd":"npm install esbuild-plugin-wasm","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-plugin-wasm","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-plugin-wasm","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library ships only a named export 'wasmLoader'. Default import is incorrect.","wrong":"import wasmLoader from 'esbuild-plugin-wasm'","symbol":"wasmLoader","correct":"import { wasmLoader } from 'esbuild-plugin-wasm'"},{"note":"Using the module with CommonJS (require) works, but the default export is not a function; only destructuring works.","wrong":"const wasmLoader = require('esbuild-plugin-wasm')","symbol":"wasmLoader","correct":"const { wasmLoader } = require('esbuild-plugin-wasm')"},{"note":"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.","wrong":"const wasm = require('./lib.wasm')","symbol":"wasm module","correct":"import wasm from './lib.wasm'"},{"note":"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.","wrong":null,"symbol":"type for wasm","correct":"import wasm from './lib.wasm'; const module: typeof wasm = wasm"}],"quickstart":{"code":"// build.js\nimport esbuild from 'esbuild';\nimport { wasmLoader } from 'esbuild-plugin-wasm';\n\nawait esbuild.build({\n  entryPoints: ['app.js'],\n  bundle: true,\n  outdir: 'out',\n  format: 'esm',\n  plugins: [wasmLoader({ mode: 'deferred' })],\n});\n\n// app.js\nimport wasm from './lib.wasm';\nconsole.log(wasm.add(1, 2));\n","lang":"javascript","description":"Shows basic usage: set up esbuild with the wasm plugin in ESM mode, then import a .wasm file."},"warnings":[{"fix":"Set format: 'esm' in esbuild build options, or use deferred mode and ensure runtime supports fetch.","message":"Top-level await is required but esbuild only supports it with 'esm' output format. Using 'iife' or 'cjs' will cause an error.","severity":"breaking","affected_versions":">=0.0.0"},{"fix":"Deploy the .wasm file to the same directory as the output JS, or adjust paths with 'publicPath' or similar.","message":"In deferred mode, the WASM binary is not bundled; it must be served alongside the output JavaScript. If missing, fetch will fail at runtime.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use deferred mode for production, or compress WASM before embedding.","message":"Embedded mode increases bundle size by ~30% due to base64 encoding. This may cause performance issues for large WASM files.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Switch to ESM import syntax (e.g., import wasm from './lib.wasm').","message":"The 'require' syntax for importing .wasm files may not work with some esbuild versions or configurations. The plugin is designed for ESM imports.","severity":"deprecated","affected_versions":">=0.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Set format: 'esm' in your esbuild config.","cause":"Using output format 'cjs' or 'iife' with esbuild-plugin-wasm, which requires 'esm'.","error":"Error: Top-level await is not supported in this output format (cjs/iife)"},{"fix":"Add wasmLoader() to the plugins list.","cause":"The plugin is not registered in the esbuild plugins array.","error":"Error: Could not resolve .../lib.wasm (maybe use the wasmLoader plugin?)"},{"fix":"Use esbuild with the wasmLoader plugin to bundle the .wasm file.","cause":"Trying to import a .wasm file directly without a bundler like esbuild that provides the loader.","error":"SyntaxError: Unexpected token 'export' (or similar parse error) when importing .wasm in Node.js without esbuild"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}