esbuild-wasm: WebAssembly Bundler

Common errors

• Error: Must call "initialize" before "build" or "transform"

  cause The WebAssembly module has not been loaded and initialized, or `initialize()` was not awaited.
  fix Ensure `await initialize({ worker: true, wasmURL: '...' });` is called and successfully completes before any `build` or `transform` operations.

• ReferenceError: require is not defined

  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.
  fix Use `import { build } from 'esbuild-wasm';` syntax in ES module files. If targeting a browser, ensure your bundler processes `esbuild-wasm` correctly.

• TypeError: esbuild.build is not a function

  cause Incorrectly attempting to access `build` from a default import or a non-destructured `require` call when `build` is a named export.
  fix For ESM, use `import { build } from 'esbuild-wasm';`. For CJS, use `const { build } = require('esbuild-wasm');` to destructure named exports.

Warnings

• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install esbuild-wasm npm
• yarn add esbuild-wasm yarn
• pnpm add esbuild-wasm pnpm

Imports

• initialize
  wrong:

  import esbuild from 'esbuild-wasm'; // esbuild-wasm does not have a default export.

  correct:

  import { initialize } from 'esbuild-wasm'

  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.
• transform
  wrong:

  const transform = require('esbuild-wasm').default.transform; // esbuild-wasm does not export a default in CJS.

  correct:

  import { transform } from 'esbuild-wasm'

  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.
• build
  wrong:

  import { build } from 'esbuild-wasm/lib/main'; // Incorrect submodule path; use the main package export.

  correct:

  import { build } from 'esbuild-wasm'

  The primary API for bundling multiple files. Like `transform`, it supports both module systems.
• BuildOptions
  wrong:

  import { BuildOptions } from 'esbuild-wasm'; // BuildOptions is a TypeScript type, not a runtime value.

  correct:

  import type { BuildOptions } from 'esbuild-wasm'

  TypeScript type for configuring the `build` function.

Quickstart

Demonstrates initializing the esbuild-wasm service and performing a basic TypeScript transformation with minification and sourcemap generation.

import { initialize, transform } from 'esbuild-wasm';

async function runWasmEsbuild() {
  // esbuild-wasm requires initialization to load the WebAssembly binary.
  // This should only be called once. For Node.js, setting 'worker: true'
  // and explicitly providing wasmURL is robust for predictable loading.
  await initialize({
    worker: true,
    wasmURL: 'https://unpkg.com/esbuild-wasm@0.28.0/esbuild.wasm' // Specify a CDN URL for predictability
  });

  const sourceCode = `
    import { someHelper } from './utils';
    const message: string = "Hello, esbuild-wasm!";
    console.log(message + someHelper());

    function someHelper() {
      return " from a helper!";
    }
  `;

  console.log('Original code:\n', sourceCode);

  // Transform TypeScript code to JavaScript, minifying it.
  const result = await transform(sourceCode, {
    loader: 'ts',
    minify: true,
    sourcemap: true,
    target: 'es2018',
  });

  console.log('\nTransformed code:');
  console.log(result.code);
  console.log('\nSourcemap:');
  console.log(result.map);

  // When using worker: true, the worker process typically exits with the main process.
  // Explicit 'stop' is usually not needed unless managing a long-lived service manually.
}

runWasmEsbuild().catch(console.error);