esbuild-wasm

library0.28.0jsnpmunverified

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.

devops http-networking serialization

npm install esbuild-wasm

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ESBUILD-WASM

esbuild-wasm

devopsjavascriptv0.28.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–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

initialize

✓ import { initialize } from 'esbuild-wasm'

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

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

✓ import { transform } from 'esbuild-wasm'

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

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

✓ import { build } from 'esbuild-wasm'

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

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

BuildOptions

✓ import type { BuildOptions } from 'esbuild-wasm'

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

TypeScript type for configuring the `build` function.

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);

Debug

Known issues

breakingesbuild 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.

affects: >=0.27.0

gotchaThe `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.

affects: >=0.1.0

gotchaWhile `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.

affects: >=0.1.0

gotchaRecent `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.

affects: >=0.28.0

Errors

Common errors & fixes

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

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

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

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.

Upgrade

Version history

0.28.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/evanw/esbuild ↗

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

homepagehttps://esbuild.github.io ↗