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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
build
✓ import { build } from 'esbuild'
✗ const esbuild = require('esbuild'); esbuild.build(...);
The primary API for bundling files. `esbuild` is primarily ESM-first for its programmatic API, though CommonJS `require` can be used with dynamic `import()` or by configuring your project for CommonJS.
transform
✓ import { transform } from 'esbuild'
✗ const esbuild = require('esbuild'); esbuild.transform(...);
Used for transforming a single string of code (e.g., TS/JSX to JS) without touching the file system. Ideal for in-memory transformations. Like `build`, primarily ESM-first for modern usage.
serve
✓ import { serve } from 'esbuild'
✗ const { serve } = require('esbuild');
Provides a development server API. Ensure the `esbuild` package is installed as a development dependency.
default import (for CLI via shim)
✓ import esbuild from 'esbuild'
✗ import * as esbuild from 'esbuild'
While `esbuild` provides named exports for its API, the `esbuild` package often acts as a JavaScript shim for the native binary. When running via `node_modules/.bin/esbuild`, it launches an external process. The programmatic API uses named exports.
This quickstart demonstrates how to use esbuild's programmatic `build` API to bundle, minify, and generate a sourcemap for a TypeScript application, targeting both modern browser and Node.js environments. It also includes basic plugin usage for logging and defines environment variables.
import { build } from 'esbuild';
const entryPoint = 'src/app.ts';
const outFile = 'dist/bundle.js';
async function bundleApp() {
try {
await build({
entryPoints: [entryPoint],
bundle: true,
minify: true,
sourcemap: true,
target: ['es2020', 'node18'],
platform: 'browser', // Or 'node', 'neutral'
outfile: outFile,
logLevel: 'info',
// Define environment variables directly for substitution
define: {
'process.env.NODE_ENV': JSON.stringify('production'),
'process.env.API_KEY': JSON.stringify(process.env.API_KEY ?? 'default_api_key')
},
// Plugins can extend esbuild's functionality
plugins: [
// Example: a simple plugin to log start/end
{
name: 'logger',
setup(build) {
build.onStart(() => {
console.log(`Starting build of ${entryPoint}...`);
});
build.onEnd(result => {
if (result.errors.length > 0) {
console.error(`Build of ${entryPoint} failed with ${result.errors.length} errors.`);
} else {
console.log(`Successfully built ${entryPoint} to ${outFile} in ${result.timeInMs}ms.`);
}
});
},
},
],
});
console.log('Build complete!');
} catch (e) {
console.error('Build failed:', e.message);
process.exit(1);
}
}
bundleApp();
esbuild --version
Debug
Known issues
breakingesbuild 0.27.0 (and other `0.x.0` releases) introduced backwards-incompatible changes. These included updated Go compiler versions, which can subtly alter behavior in edge cases related to garbage collection, memory allocation, and executable formats. It also raised minimum operating system requirements (e.g., Linux kernel 3.2+, macOS 12+). [cite: v0.27.0 release notes, 16, 17, 18]fixPin the exact version of `esbuild` in your `package.json` (e.g., `"esbuild": "0.27.0"`) or use a patch-only range (`^0.27.0` or `~0.27.0`) to avoid unexpected breaking changes from minor version increments in `0.x.x` releases. Ensure your operating system meets the new minimum requirements.
affects: >=0.27.0
breakingesbuild versions 0.24.2 and earlier had a moderate severity vulnerability (CVE-2024-23334) in its development server, allowing external websites to send requests and read responses, potentially exposing sensitive information.fixUpgrade `esbuild` to version `0.25.0` or newer. If `esbuild` is a transitive dependency (e.g., via Angular), use `npm audit fix --force` or configure `package.json` `overrides` to enforce `"esbuild": "^0.25.0"`.
affects: <=0.24.2
breakingThe minimum required Node.js version for esbuild's JavaScript API was increased from Node 12 to Node 18 due to incompatibilities with JavaScript generated for `esbuild-wasm` and older Node.js versions (specifically `crypto.getRandomValues`).fixEnsure your project uses Node.js version 18 or later. Check the official Node.js release schedule for supported versions.
affects: >=0.19.12 (published in 2024)
gotchaWhen bundling for a Node.js environment, it is crucial to explicitly set the `platform` option to `'node'`. Failing to do so can lead to `Could not resolve` errors for Node.js built-in modules (e.g., `https`, `fs`) as esbuild will try to bundle them for a browser environment.fixAdd `platform: 'node'` to your `esbuild` configuration (CLI: `--platform=node`) to correctly handle Node.js-specific modules and behavior.
affects: all
gotchaesbuild sometimes rewrites top-level `let`, `const`, and `class` declarations as `var` declarations for correctness in bundling. While `const` mutations are prevented, this can be unexpected if strict variable scoping is assumed.fixBe aware of this internal transformation. Ensure your code does not rely on strict `let`/`const` block-scoping behavior at the top level in ways that might conflict with `var` hoisting in complex bundling scenarios. Test your bundled output carefully.
affects: all
deprecatedThe `using` declarations inside `switch` case/default clauses, previously supported and implemented, are now a syntax error. This aligns with a specification change due to confusion around scope within `switch` statements.fixWrap `using` declarations within explicit block statements (`{...}`) inside `switch` cases to maintain correct scoping and syntax. E.g., `case 'read': { using readLock = db.read(); return readAll(readLock); }`. affects: >=0.27.0 (specifically related to a change in ECMAScript proposal)
Errors
Common errors & fixes
✘ [ERROR] Could not resolve "some-module"
esbuild cannot find the specified module in your `node_modules` or resolve its path.
fixVerify that the module is installed (`npm install some-module`), check for typos in the import path, and ensure correct casing. If it's a Node.js built-in module, ensure `platform: 'node'` is set in your build configuration.
✘ [ERROR] Expected ";" but found "}" (or similar syntax errors)
There is a syntax error in your JavaScript, TypeScript, or JSX code that esbuild cannot parse.
fixReview the file and line number indicated in the error message. Ensure your code adheres to correct syntax for the target environment. Use a linter (e.g., ESLint) to catch syntax errors proactively.
The package "https" wasn't found on the file system but is built into node. Are you trying to bundle for node? You can use "platform: 'node'" to do that, which will remove this error.
esbuild is attempting to bundle a Node.js built-in module (like `https`, `fs`, `path`) but is configured for a browser environment.
fixAdd `platform: 'node'` to your esbuild configuration. For the CLI, use `--platform=node`. For the API, set `platform: 'node'` in the build options object.
Error: Conflict: The output files "index.js" and "index.js" are being generated for different entry points. You need to use a different naming scheme.
This typically occurs when dynamic imports or multiple entry points would result in output files with identical base names (e.g., two `index.js` files from different library paths).
fixUse a more specific naming scheme for your entry points or chunk names. For CLI, consider `--entry-names=[dir]/[name]` or `--chunk-names=[name]-[hash]`. Programmatically, define `entryNames` or `chunkNames` in your build options.
Audit
Dependencies
@esbuild/darwin-x64optionalBinary executable for macOS ARM64. `esbuild` installs the appropriate platform-specific package automatically.
@esbuild/linux-x64optionalBinary executable for Linux x64. `esbuild` installs the appropriate platform-specific package automatically.
@esbuild/win32-x64optionalBinary executable for Windows x64. `esbuild` installs the appropriate platform-specific package automatically.
esbuild-wasmoptionalWebAssembly fallback for platforms without a native binary, or for browser environments.