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')
This package (`esbuild-android-arm64`) provides a platform-specific binary and does not expose direct JavaScript imports. The `build` function is imported from the main `esbuild` package. The `esbuild` API is primarily designed for ESM; while CommonJS `require` may work for older versions or specific setups, ESM is the recommended approach for modern Node.js and TypeScript projects. Type definitions are shipped with the package.
transform
✓ import { transform } from 'esbuild'
✗ const transform = require('esbuild').transform
The `transform` function is imported from the main `esbuild` package and is used for single-file transformations without bundling. Same ESM/CJS considerations as `build` apply.
Plugin
✓ import type { Plugin } from 'esbuild'
✗ import { Plugin } from 'esbuild'
The `Plugin` interface is imported from the main `esbuild` package. It is used for type hinting when creating custom esbuild plugins and is not a runtime value. Use `import type` for type-only imports in TypeScript to avoid bundling unused imports.
This quickstart demonstrates a basic esbuild configuration to bundle a TypeScript application, including generating source maps, minifying code, targeting specific environments, and incorporating a simple custom plugin for build lifecycle logging. This code leverages the main `esbuild` package, which utilizes this binary.
import { build } from 'esbuild';
import path from 'path';
import process from 'process';
// Define your entry point and output file paths
const entryPoint = path.resolve(process.cwd(), 'src/index.ts');
const outFile = path.resolve(process.cwd(), 'dist/bundle.js');
async function runBuild() {
try {
// Configure and run the esbuild bundling process
await build({
entryPoints: [entryPoint],
bundle: true, // Enable bundling
outfile: outFile, // Specify the output file
platform: 'node', // Target Node.js environment
format: 'esm', // Output ES Module format
sourcemap: true, // Generate source maps
minify: true, // Enable minification
target: ['es2020', 'node18'], // Target JavaScript and Node.js versions
define: { 'process.env.NODE_ENV': '"production"' }, // Define global variables
plugins: [
// Example of a simple esbuild plugin logging build events
{
name: 'my-build-logger',
setup(build) {
build.onStart(() => {
console.log('esbuild process started...');
});
build.onEnd(result => {
if (result.errors.length > 0) {
console.error('esbuild finished with errors:', result.errors);
} else {
console.log('esbuild finished successfully!');
}
});
}
}
]
});
console.log(`Application bundled to ${outFile}`);
} catch (error) {
console.error('esbuild failed during build:', error);
process.exit(1);
}
}
runBuild();
Debug
Known issues
breakingesbuild `v0.27.0` introduced deliberate backwards-incompatible changes. Relying on caret (`^`) or tilde (`~`) ranges for `esbuild` may lead to unexpected behavior. It is strongly recommended to pin the exact version (`0.x.y`) in `package.json` or use `~0.x.y` to limit updates to patch releases.fixPin `esbuild` to an exact version (`"esbuild": "0.x.y"`) or use `"esbuild": "~0.x.y"` to limit updates to patch releases.
affects: >=0.27.0
gotchaIn esbuild `v0.27.6`, TypeScript parameter properties were incorrectly generated as class fields even when the configured target environment did not support them, potentially leading to runtime errors in older environments. This was fixed in `v0.27.7`.fixUpgrade `esbuild` to `v0.27.7` or later if using TypeScript parameter properties with targets that don't support class fields.
affects: 0.27.6
gotchaesbuild versions `0.25.11` through `0.27.3` introduced regressions in parsing and minifying specific CSS media query syntaxes (e.g., `<media-type> and <media-condition-without-or>`). This could lead to incorrect output or failed minification.fixUpgrade `esbuild` to `v0.27.4` or later to resolve issues with CSS media query handling.
affects: 0.25.11 - 0.27.3
gotchaesbuild versions prior to `v0.27.1` had a bug where `var` declarations nested inside `if` statements in ES modules imported via `require` (which are wrapped) might not be hoisted correctly, leading to runtime errors.fixUpgrade `esbuild` to `v0.27.1` or later to ensure correct `var` hoisting behavior in complex ES module `require` scenarios.
affects: <0.27.1
gotchaAs of `v0.26.0`, esbuild packages are published using GitHub's trusted publishing. While this enhances supply chain security by leveraging automated workflows for package publication, it represents a change in the distribution mechanism.fixNo direct fix needed by consumers, but awareness of the publishing mechanism is beneficial for supply chain security audits.
affects: >=0.26.0
Errors
Common errors & fixes
Error: No matching binary found for esbuild-android-arm64.
The esbuild core package could not locate a compatible pre-built binary for the current platform/architecture, or the `esbuild-android-arm64` package was installed on an incompatible system.
fixEnsure the correct `esbuild` binary package (e.g., `esbuild-linux-x64`, `esbuild-win32-x64`) is installed for your specific host or target environment. If cross-compiling or deploying to Android ARM 64-bit, ensure the `esbuild-android-arm64` package is correctly installed and accessible by the main `esbuild` package.
SyntaxError: Cannot use import statement outside a module
Attempting to use ES module `import` syntax in a CommonJS (`require`) environment without proper configuration (e.g., `"type": "module"` in `package.json`).
fixConfigure your `package.json` with `"type": "module"` to enable ES modules, or rename your file to `.mjs`. Alternatively, if you must use CommonJS, use dynamic `import('esbuild').then(...)` or ensure you're using an `esbuild` version and API call that supports CommonJS `require` where applicable. Audit
Dependencies
No dependency data recorded yet.