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 * as esbuild from 'esbuild';
await esbuild.build({
entryPoints: ['src/app.js'],
bundle: true,
outfile: 'dist/bundle.js',
});
✗ const esbuild = require('esbuild'); // CJS is supported, but ESM is generally preferred for modern Node.js development and type safety.
The primary API is the 'build' function, which returns a promise. Async/await is the recommended pattern. While CommonJS 'require' still works, ESM imports are standard for new projects.
Service
✓ import { startService } from 'esbuild';
const service = await startService();
try {
// Use service for operations
} finally {
service.stop();
}
For long-running processes or multiple builds, starting a service can be more efficient than calling `build` directly multiple times, as it avoids repeated startup overhead.
transform
✓ import * as esbuild from 'esbuild';
const result = await esbuild.transform('const a = 1;', {
loader: 'js',
minify: true,
});
console.log(result.code);
✗ import { transform } from 'esbuild'; // Incorrect if 'transform' is not a named export directly from 'esbuild'.
The 'transform' API allows processing a single string of code rather than files, useful for in-memory transformations or plugin development. It's usually accessed as 'esbuild.transform'.
This quickstart demonstrates how to bundle a TypeScript entry point for a Node.js environment, including minification, sourcemaps, and a basic logging plugin, using esbuild's JavaScript API.
import * as esbuild from 'esbuild';
import path from 'path';
import { fileURLToPath } from 'url';
// Emulate __dirname for ESM context
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
const entryPoint = path.resolve(__dirname, 'src/index.ts');
const outputDir = path.resolve(__dirname, 'dist');
console.log(`Bundling ${entryPoint} to ${outputDir}/bundle.js`);
try {
await esbuild.build({
entryPoints: [entryPoint],
bundle: true,
minify: true,
sourcemap: true,
platform: 'node', // or 'browser' or 'neutral'
format: 'esm', // or 'cjs' or 'iife'
outfile: path.join(outputDir, 'bundle.js'),
// Externalize node built-ins for 'node' platform to avoid bundling them
external: ['fs', 'path', 'url'],
logLevel: 'info',
define: { 'process.env.NODE_ENV': '"production"' },
// Add a simple plugin example to show esbuild's extensibility
plugins: [{
name: 'log-plugin',
setup(build) {
build.onStart(() => {
console.log('Build started!');
});
build.onEnd(result => {
if (result.errors.length > 0) {
console.error('Build failed:', result.errors);
} else {
console.log('Build finished successfully with', result.warnings.length, 'warnings.');
}
});
},
}],
});
console.log('Build complete!');
} catch (e) {
console.error('Build failed:', e.message);
process.exit(1);
}
esbuild --version
Debug
Known issues
breakingesbuild's `0.x.x` versioning scheme (e.g., v0.27.0, v0.28.0) does not follow strict semantic versioning where minor versions only introduce compatible changes. Minor version increments in esbuild can and often do contain backwards-incompatible changes.fixPin the exact version of `esbuild` in `package.json` (e.g., `"esbuild": "0.28.0"`) or use a version range that only accepts patch upgrades (`^0.28.0` or `~0.28.0`) to avoid unexpected breaking changes.
affects: >=0.17.0
breakingThe minimum required Node.js version for esbuild's JavaScript API increased to Node 18 due to an incompatibility with the `esbuild-wasm` package and older Node versions. Using older Node versions will lead to runtime errors.fixEnsure your project's Node.js environment is version 18 or later. Update your `engines` field in `package.json` to reflect this requirement.
affects: >=0.23.0
breakingesbuild v0.28.0 introduced integrity checks to the fallback download path for platform-specific binaries. While this improves security, it was deemed a breaking change due to potential subtle behavior differences, especially in complex installation scenarios or restricted environments.fixReview your esbuild installation and build processes, especially in environments with strict network policies or custom binary management, to ensure compatibility with the new integrity checks. Upgrade to Go 1.26 or newer for underlying Go compiler changes if encountering issues.
affects: >=0.28.0
gotchaWhen bundling for the `node` platform, esbuild by default *bundles* Node.js built-in modules. If you intend for Node.js built-in modules (like `fs`, `path`, `http`) to be resolved at runtime by Node.js, they must be explicitly marked as external.fixAdd `platform: 'node'` and include an `external: ['module-name']` array in your `esbuild` configuration to prevent bundling Node.js native modules. Alternatively, use `packages: 'external'` in the CLI or API options for all modules.
affects: All versions
gotchaUpdates to the underlying Go compiler (e.g., from Go 1.25.7 to 1.26.1 in esbuild v0.28.0) can subtly change esbuild's behavior in edge cases. This might affect garbage collection, stack allocation, or executable formats, leading to unexpected runtime characteristics.fixIf experiencing unusual behavior after an esbuild upgrade involving a Go compiler update, review the official Go release notes for the new version. Test thoroughly and consider isolating esbuild versions if critical stability is required.
affects: >=0.28.0 (and other versions with Go compiler upgrades)
gotchaUsing esbuild's development server (`--serve`) in conjunction with custom hostname mappings (e.g., via `/etc/hosts`) was intentionally broken in v0.25.0 for security reasons and re-enabled as an opt-in feature in later versions for a single domain name.fixFor versions that re-enabled the feature, configure `--serve=local.example.com:8000` to specify the allowed domain. If on an affected version, upgrade esbuild or avoid custom hostname mappings with `--serve`.
affects: 0.25.0 - 0.27.x
Errors
Common errors & fixes
✘ [ERROR] Could not resolve "some-module"
esbuild cannot find the specified module. This often happens if the module is not installed, misspelled, or if path resolution is misconfigured.
fixVerify `some-module` is correctly installed in `node_modules` and its name is correctly spelled. Check `tsconfig.json` paths or `esbuild` `resolveExtensions` options. For Node.js built-in modules in a browser target, use `external` or set `platform: 'node'`.
✘ [ERROR] Expected ";" but found "}"
This is a general syntax error encountered by esbuild during parsing. It indicates malformed JavaScript or TypeScript code.
fixReview the file and line number indicated in the error message. Ensure your code adheres to correct syntax. Use linters (e.g., ESLint, Prettier) to catch syntax issues pre-build.
your config.{ts,js} was not successfully executed
This error, common in frameworks using esbuild for configuration files (e.g., TinaCMS), means the configuration file compiled but failed to execute, often due to importing frontend-specific code (e.g., `window`, DOM APIs) or code requiring special loaders/plugins in a Node.js execution environment.
fixEnsure your esbuild configuration file and any modules it imports are compatible with a Node.js runtime. Avoid importing browser-specific APIs or components. Refactor imports to be more granular if a specific part of a module causes issues.
Top-level variables in an entry point module should never end up in the global scope when running esbuild's output in a browser.
This is not an error message but a common misconception/issue. If your bundled code's top-level variables become global in a browser, it means you're not using an appropriate output format.
fixWhen targeting a browser, always use `--format=iife` (Immediately Invoked Function Expression) with `<script src="...">` or `--format=esm` for `<script type="module" src="...">`. This ensures proper module scoping and prevents global variable collisions.
Audit
Dependencies
esbuildrequiredThis package is a platform-specific binary dependency for the main 'esbuild' package, which orchestrates its use.