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 { build } = require('esbuild')
While `require` works, esbuild encourages ESM for its API. The `build` function is the primary method for programmatically invoking esbuild. Asynchronous API is recommended, especially when using plugins.
transform
✓ import { transform } from 'esbuild'
✗ import esbuild from 'esbuild'; esbuild.transform(...)
The `transform` function is used for processing individual code strings rather than entire file bundles. It's a named export, not a property of a default export.
ServeOptions
✓ import type { ServeOptions } from 'esbuild'
✗ import { ServeOptions } from 'esbuild'
Type imports should use `import type` to ensure they are stripped during compilation and do not introduce runtime dependencies.
This quickstart demonstrates how to programmatically use esbuild's `build` API to bundle, minify, and create a sourcemap for a TypeScript entry file, targeting a Node.js environment.
import { build } from 'esbuild';
import path from 'path';
import url from 'url';
const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
async function bundleCode() {
try {
await build({
entryPoints: [path.resolve(__dirname, 'src/index.ts')],
bundle: true,
minify: true,
sourcemap: true,
outfile: path.resolve(__dirname, 'dist/bundle.js'),
platform: 'node',
target: 'es2020',
logLevel: 'info',
});
console.log('Build successful: dist/bundle.js created.');
} catch (error) {
console.error('Build failed:', error);
process.exit(1);
}
}
bundleCode();
// To make this runnable, create src/index.ts:
// export function greet(name: string): string {
// return `Hello, ${name}!`;
// }
// console.log(greet('esbuild user'));
Debug
Known issues
breakingesbuild explicitly ships backwards-incompatible changes in minor versions (e.g., v0.27.0, v0.24.0, v0.23.0). It is crucial to pin exact versions or use only patch-level ranges (`~0.X.Y`) in `package.json` to prevent unexpected build failures upon upgrade.fixUpdate your `package.json` to use exact version pinning (e.g., `"esbuild": "0.28.0"`) or tilde ranges (e.g., `"esbuild": "~0.28.0"`) and thoroughly test before deploying.
affects: >=0.17.0
gotchaWhen bundling for Node.js, `esbuild` does not automatically externalize Node.js built-in modules (like `fs`, `path`, `https`) by default unless `--platform=node` is explicitly set. Without this, it will attempt to bundle them, leading to errors like 'Could not resolve "https"'.fixAlways use `--platform=node` when bundling applications intended to run in a Node.js environment. For the JS API, set `platform: 'node'` in the build options.
affects: All versions
breakingesbuild's JavaScript API increased its minimum required Node.js version from 12 to 18 in a 2024 release. Running `esbuild` via its JS API on older Node.js versions will result in incompatibility errors.fixUpgrade your Node.js runtime to version 18 or later. Node.js 18 is the oldest version currently supported by esbuild's JavaScript API.
affects: >=0.19.12 (versions published in 2024 and later)
gotchaesbuild treats TypeScript types as comments and strips them without performing type checking. This means type errors will not halt the esbuild process. It is recommended to enable the `isolatedModules` TypeScript compiler option.fixRun the TypeScript type checker (e.g., `tsc --noEmit`) alongside esbuild in your build pipeline. In `tsconfig.json`, set `"compilerOptions": { "isolatedModules": true }` to prevent features that rely on cross-file type references from mis-compiling. affects: All versions
breakingThe behavior of TypeScript parameter properties and class fields changed in v0.27.7, specifically regarding their lowering when the target environment does not support class fields. Previous versions might have incorrectly generated class fields, leading to runtime issues.fixReview TypeScript code using parameter properties or class fields, especially when targeting older environments. Ensure `tsconfig.json`'s `target` and `useDefineForClassFields` options are correctly configured for your desired runtime behavior.
affects: >=0.27.7
breakingSupport for macOS 10.15 Catalina was dropped in a 2024 release (v0.24.0) because the Go programming language (which esbuild is written in) dropped support for it. This affects users running older macOS versions.fixUpgrade your macOS operating system to macOS 11 Big Sur or later to continue using recent esbuild versions.
affects: >=0.24.0
Errors
Common errors & fixes
✘ [ERROR] Could not resolve "some-module"
esbuild could not find the imported module in `node_modules` or the specified paths.
fixEnsure the module is installed (`npm install some-module`), spelled correctly, and check your `resolve` options in esbuild configuration. If it's a Node.js built-in module, ensure `platform: 'node'` is set.
✘ [ERROR] Expected ";" but found "}"
There is a syntax error in your JavaScript or TypeScript code.
fixReview the file and line number indicated in the error message for incorrect syntax. Use a linter (like ESLint) to catch these errors before running esbuild.
error: Promise resolution is still pending but the event loop has already resolved
This error can occur in Deno when esbuild's long-lived child process is not explicitly terminated after `esbuild.stop()` is called, particularly with Deno's testing API.
fixEnsure `esbuild.stop()` is properly called and awaited, or investigate specific Deno runtime issues related to child process handling, especially after Deno 1.40.0.
ERROR: your schema was not successfully built / ERROR: your config.{ts,js} was not successfully executed
Often seen in frameworks using esbuild internally (e.g., TinaCMS), this indicates a syntax/semantic error in the configuration file or an imported file, or attempting to run frontend-specific code (e.g., using `window`) in a Node.js environment during the build process.
fixInspect the mentioned configuration file and its imports for syntax errors or accidental inclusion of browser-specific code. Refactor imports to be more granular, importing only what's strictly needed for the build environment.
Audit
Dependencies
No dependency data recorded yet.