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')
The esbuild API is predominantly designed for ES Modules. While 'require' may function in some CommonJS environments, direct ESM usage is the idiomatic and recommended approach for modern Node.js projects. Ensure your `package.json` specifies `"type": "module"` or use `.mjs` file extensions for direct ESM imports.
transform
✓ import { transform } from 'esbuild'
✗ import esbuild from 'esbuild'; esbuild.transform
Most esbuild API functions are provided as named exports. There is no default export for the API module, and attempting to destructure functions from a non-existent default import will result in an error.
buildSync
✓ import { buildSync } from 'esbuild'
✗ import { build } from 'esbuild'; build.sync()
The synchronous `buildSync` function is a named export. While useful for CLI tools or specific blocking scenarios, synchronous API calls are generally discouraged for long-running operations in Node.js as they block the event loop. Prefer the asynchronous `build` function when possible.
This quickstart demonstrates how to programmatically use esbuild's `build` API to bundle, minify, transpile TypeScript, generate sourcemaps, and define environment-specific constants for a Node.js target, illustrating a common build setup.
import { build } from 'esbuild';
import path from 'path';
const projectRoot = process.cwd();
const entryPoint = path.join(projectRoot, 'src', 'index.ts');
const outFile = path.join(projectRoot, 'dist', 'bundle.js');
async function runBuild() {
console.log(`Starting build for ${entryPoint}...`);
try {
await build({
entryPoints: [entryPoint],
bundle: true,
minify: true,
sourcemap: true,
outfile: outFile,
platform: 'node', // Can be 'browser', 'node', or 'neutral'
target: ['es2020', 'node18'], // Specify target environments
logLevel: 'info',
banner: { js: '// Built by esbuild on ' + new Date().toISOString() },
define: {
'process.env.NODE_ENV': '"production"', // Define global constants
'__APP_VERSION__': '"1.0.0"' // Example custom constant
},
external: ['lodash', 'axios'], // Exclude these packages from the bundle
});
console.log(`Build successful: ${entryPoint} -> ${outFile}`);
} catch (error) {
console.error('Build failed with errors:', error);
process.exit(1);
}
}
runBuild();
esbuild --version
Debug
Known issues
breakingVersion 0.27.0 introduced deliberate backwards-incompatible changes. To prevent unexpected breakage, it is strongly recommended to pin the exact `esbuild` version in `package.json` (e.g., `'esbuild': '0.26.0'`) or restrict updates to patch-level releases using tilde/caret ranges carefully (e.g., `'esbuild': '~0.26.0'` but be aware this might still pull in breaking changes for versions like 0.27.x if used with ^0.26.0).fixReview the specific release notes for breaking changes before upgrading. Pin exact versions (`"esbuild": "0.27.0"`) or use dependency management tools with lockfiles to control updates.
affects: >=0.27.0
gotchaNetBSD is not among Node.js's officially supported platforms. While `esbuild-netbsd-64` provides the necessary binary, its stability and full functionality may vary depending on the specific Node.js installation and patches on the NetBSD system. This is a platform-level consideration, not a direct fault of esbuild itself.fixConsult NetBSD-specific Node.js documentation or community forums for best practices regarding Node.js compatibility and stability on the platform. Consider using an officially supported platform if guaranteed behavior is critical for your application.
affects: >=0.15.18
gotchaSeveral regressions were identified and fixed in previous versions related to CSS media query parsing and minification. Specifically, versions from `0.25.11` to `0.27.4` might have produced incorrect output or failed to properly handle certain media query structures (e.g., `or` clauses), as well as issues with removal of duplicate rules during minification.fixUpgrade to esbuild v0.27.5 or a later version to ensure correct handling and minification of CSS media queries.
affects: >=0.25.11 <0.27.5
gotchaAn issue existed where async generators transformed by esbuild did not function correctly when polled concurrently (e.g., using `yield* inner()`), specifically for versions from `0.19.0` until `0.27.5`. This could lead to unexpected runtime behavior.fixUpgrade to esbuild v0.27.5 or a newer version to resolve the async generator concurrent polling bug.
affects: >=0.19.0 <0.27.5
gotchaA specific bundler bug in versions prior to `0.27.1` caused incorrect hoisting of `var` declarations that were nested inside an `if` statement, particularly when an ES module was imported using `require` (which wraps it). This could lead to runtime errors.fixUpgrade to esbuild v0.27.1 or a later version to ensure correct hoisting behavior for `var` declarations in bundled code.
affects: >=0.15.18 <0.27.1
Errors
Common errors & fixes
Error: spawnSync ./esbuild ENOENT
The esbuild binary could not be found or executed. This often indicates that the platform-specific binary package failed to install correctly (e.g., due to network issues, corrupted cache, or incompatible platform), or the binary lacks execute permissions.
fixCheck your npm installation logs for errors related to 'esbuild-YOUR_PLATFORM' (e.g., `esbuild-netbsd-64`). Try clearing npm cache (`npm cache clean --force`) and reinstalling esbuild. Ensure the binary has executable permissions (`chmod +x node_modules/esbuild/esbuild`). If on NetBSD, verify Node.js's ability to execute external binaries.
esbuild: command not found
The `esbuild` command-line executable is not available in your system's PATH. This typically happens when esbuild is installed as a local dependency and you're trying to run it directly from the terminal, or if a global installation failed.
fixIf esbuild is a local dependency, use `npx esbuild ...` or define a script in your `package.json` (e.g., `"build": "esbuild src/index.ts --bundle --outfile=dist/main.js"`). If you intend to use it globally, ensure it was installed with `npm install -g esbuild` and your global npm bin directory is in your PATH.
Error: "/path/to/project/node_modules/esbuild/lib/main.js" is an ES module file cannot be 'require'd. Instead, change the requiring code to use 'import'
You are attempting to load esbuild's main entry point (which is an ES Module) using Node.js's CommonJS `require()` function from a CommonJS context.
fixUpdate your code to use `import { build } from 'esbuild'` and ensure your Node.js project is configured for ES Modules. This typically involves adding `"type": "module"` to your `package.json` file or renaming your consuming file to have a `.mjs` extension. Audit
Dependencies
esbuildoptionalThis package provides the platform-specific executable for the main 'esbuild' package, which consumes this binary to run on NetBSD systems.