{"id":10810,"library":"esbuild-wasm","title":"esbuild-wasm: WebAssembly Bundler","description":"esbuild-wasm is the WebAssembly-based distribution of esbuild, a high-performance JavaScript and TypeScript bundler and minifier. It provides the core bundling and transformation capabilities of esbuild in a cross-platform WebAssembly binary, suitable for environments like web browsers, Deno, and Bun, or Node.js where a native binary might not be ideal or available. The current stable version is v0.28.0. The project maintains a rapid release cadence, often introducing new features and bug fixes, and sometimes includes deliberate backwards-incompatible changes, as highlighted in releases like v0.27.0. Its key differentiator from the primary `esbuild` package is its WebAssembly implementation, offering broader environment compatibility, though it might have slight performance variations compared to the native binary. Users should be aware of the explicit `initialize` step required for its operation.","status":"active","version":"0.28.0","language":"javascript","source_language":"en","source_url":"https://github.com/evanw/esbuild","tags":["javascript","typescript"],"install":[{"cmd":"npm install esbuild-wasm","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-wasm","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-wasm","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Required to load the WebAssembly binary before any other API calls. This step is specific to esbuild-wasm and is crucial for its operation in any environment.","wrong":"import esbuild from 'esbuild-wasm'; // esbuild-wasm does not have a default export.","symbol":"initialize","correct":"import { initialize } from 'esbuild-wasm'"},{"note":"Used for transforming individual code strings or files without performing full bundling. The package supports both ESM `import` and CJS `require` patterns due to its `exports` configuration.","wrong":"const transform = require('esbuild-wasm').default.transform; // esbuild-wasm does not export a default in CJS.","symbol":"transform","correct":"import { transform } from 'esbuild-wasm'"},{"note":"The primary API for bundling multiple files. Like `transform`, it supports both module systems.","wrong":"import { build } from 'esbuild-wasm/lib/main'; // Incorrect submodule path; use the main package export.","symbol":"build","correct":"import { build } from 'esbuild-wasm'"},{"note":"TypeScript type for configuring the `build` function.","wrong":"import { BuildOptions } from 'esbuild-wasm'; // BuildOptions is a TypeScript type, not a runtime value.","symbol":"BuildOptions","correct":"import type { BuildOptions } from 'esbuild-wasm'"}],"quickstart":{"code":"import { initialize, transform } from 'esbuild-wasm';\n\nasync function runWasmEsbuild() {\n  // esbuild-wasm requires initialization to load the WebAssembly binary.\n  // This should only be called once. For Node.js, setting 'worker: true'\n  // and explicitly providing wasmURL is robust for predictable loading.\n  await initialize({\n    worker: true,\n    wasmURL: 'https://unpkg.com/esbuild-wasm@0.28.0/esbuild.wasm' // Specify a CDN URL for predictability\n  });\n\n  const sourceCode = `\n    import { someHelper } from './utils';\n    const message: string = \"Hello, esbuild-wasm!\";\n    console.log(message + someHelper());\n\n    function someHelper() {\n      return \" from a helper!\";\n    }\n  `;\n\n  console.log('Original code:\\n', sourceCode);\n\n  // Transform TypeScript code to JavaScript, minifying it.\n  const result = await transform(sourceCode, {\n    loader: 'ts',\n    minify: true,\n    sourcemap: true,\n    target: 'es2018',\n  });\n\n  console.log('\\nTransformed code:');\n  console.log(result.code);\n  console.log('\\nSourcemap:');\n  console.log(result.map);\n\n  // When using worker: true, the worker process typically exits with the main process.\n  // Explicit 'stop' is usually not needed unless managing a long-lived service manually.\n}\n\nrunWasmEsbuild().catch(console.error);","lang":"typescript","description":"Demonstrates initializing the esbuild-wasm service and performing a basic TypeScript transformation with minification and sourcemap generation."},"warnings":[{"fix":"Always pin the exact version of `esbuild-wasm` in your `package.json` (e.g., `\"esbuild-wasm\": \"0.28.0\"`) or use a patch-only range like `~0.28.0` to avoid unexpected breaking changes. Consult release notes before upgrading.","message":"esbuild and esbuild-wasm can introduce backwards-incompatible changes even in minor versions. Release v0.27.0 explicitly noted this and advised pinning exact versions.","severity":"breaking","affected_versions":">=0.27.0"},{"fix":"Ensure `await initialize({ wasmURL: '...' });` (for browsers/custom) or `await initialize({ worker: true });` (for Node.js) is called once at the start of your application lifecycle.","message":"The `esbuild-wasm` package requires explicit initialization via `initialize()` before any other API calls (like `build` or `transform`). Failing to do so will result in an error.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Benchmark both `esbuild` and `esbuild-wasm` in your specific Node.js environment if performance is critical. Consider the native `esbuild` package for Node.js if maximum speed is required and cross-platform binary distribution is not a concern.","message":"While `esbuild-wasm` offers broad environment compatibility, it is generally much slower (potentially 10x slower) than the native `esbuild` package, especially in Node.js environments.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Review the release notes for new features and verify compatibility with your target browsers or runtimes. Adjust `target` options in esbuild if necessary to compile down unsupported syntax for broader compatibility.","message":"Recent `esbuild` releases, such as v0.28.0, add support for new web standards like `with { type: 'text' }` imports. While beneficial, ensure your target environments and tooling are compatible if relying on such features.","severity":"gotcha","affected_versions":">=0.28.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `await initialize({ worker: true, wasmURL: '...' });` is called and successfully completes before any `build` or `transform` operations.","cause":"The WebAssembly module has not been loaded and initialized, or `initialize()` was not awaited.","error":"Error: Must call \"initialize\" before \"build\" or \"transform\""},{"fix":"Use `import { build } from 'esbuild-wasm';` syntax in ES module files. If targeting a browser, ensure your bundler processes `esbuild-wasm` correctly.","cause":"Attempting to use `require()` in an ES module context (e.g., a `.mjs` file or a file in a `\"type\": \"module\"` package) or browser environment.","error":"ReferenceError: require is not defined"},{"fix":"For ESM, use `import { build } from 'esbuild-wasm';`. For CJS, use `const { build } = require('esbuild-wasm');` to destructure named exports.","cause":"Incorrectly attempting to access `build` from a default import or a non-destructured `require` call when `build` is a named export.","error":"TypeError: esbuild.build is not a function"}],"ecosystem":"npm"}