esbuild Linux 64-bit Binary

Common errors

• Error: You installed esbuild on another platform than the one you're currently using.

  cause The `esbuild` main package detected a platform-specific binary (e.g., `esbuild-darwin-arm64`) that does not match the current operating system and architecture (e.g., running in a Linux container). This often happens when `node_modules` is copied between different environments.
  fix Remove `node_modules` and `package-lock.json` (or `yarn.lock`) and run `npm install` (or `yarn install`) directly within the target environment (e.g., inside the Docker container). Make sure `node_modules` is excluded from copy operations in your deployment pipeline.

• Error: Cannot find module 'esbuild-linux-64'

  cause Attempting to directly `import` or `require` the `esbuild-linux-64` package from JavaScript/TypeScript code. This package is a native binary, not a JavaScript module for direct consumption.
  fix Import `esbuild` instead of `esbuild-linux-64`. The main `esbuild` package dynamically loads the correct platform-specific binary. For example: `import { build } from 'esbuild';`.

• esbuild: command not found

  cause The `esbuild` executable is not in the system's PATH, or the installation of the main `esbuild` package (which manages the binary) failed to link correctly, or `esbuild-linux-64` was installed without the main `esbuild` package.
  fix Ensure `esbuild` (the main package) is installed correctly, typically as a `devDependency`. Use `npx esbuild` to run the local CLI, or ensure `$(npm bin)` is in your PATH. If `esbuild-linux-64` was installed standalone, it won't provide the `esbuild` CLI command directly, you need the main `esbuild` package.

• Unsupported target environment

  cause Esbuild's output target (`--target`) is set to an environment that does not support certain language features used in the source code, or a Node.js version older than required is being used. This could be due to `Uint8Array.fromBase64` not being available or other syntax incompatibilities.
  fix Adjust the `--target` option in your esbuild configuration (e.g., `--target=es2022` or `--target=node18`) to match your intended runtime environment. Ensure your Node.js version meets esbuild's minimum requirements, especially for recent features.

Warnings

• breaking Esbuild releases, particularly major versions (e.g., v0.27.0), often contain backwards-incompatible changes. Users are strongly advised to pin exact versions or use patch-only version ranges (e.g., `^0.26.0`, `~0.26.0`) in `package.json` to prevent unexpected breakages during updates.
  Fix: Pin the `esbuild` package version in `package.json` (e.g., `"esbuild": "0.28.0"`) or use `~` for patch updates (e.g., `"esbuild": "~0.28.0"`). Regularly review the changelog before upgrading.
• gotcha Using platform-specific binaries like `esbuild-linux-64` in cross-platform environments (e.g., developing on macOS/Windows and deploying to a Linux Docker container) can lead to 'platform mismatch' errors.
  Fix: Ensure `npm install` runs within the target environment (e.g., inside the Docker container), rather than copying `node_modules` from a different OS/architecture. Add `node_modules` to `.dockerignore`. Alternatively, consider `esbuild-wasm` for full platform portability, though with a performance penalty.
• breaking Esbuild's minimum Node.js version requirement for its JavaScript API increased from Node 12 to Node 18 (as of `0.23.0` in 2024). Running esbuild with older Node.js versions will result in incompatibilities.
  Fix: Ensure your Node.js environment is version 18 or later. Update Node.js if necessary. The `engines` field `"node": ">=12"` in `esbuild-linux-64`'s `package.json` may be outdated or refer to older core compatibility.
• gotcha Mixing CommonJS (CJS) and ES Modules (ESM) in a Node.js project bundled with esbuild can lead to interoperability issues, especially with dynamic imports or complex `exports` maps in `package.json`.
  Fix: When bundling for Node.js (`--platform=node`), generally use `--format=cjs` for maximum compatibility with npm packages. If using ESM, be aware of Node.js's CJS/ESM interoperability limitations and potential need for polyfills for features like top-level await.
• breaking As of v0.27.0, esbuild's binary loader uses `Uint8Array.fromBase64` if available, and specific Go compiler updates (e.g., Go 1.26 in `v0.28.0`) have raised minimum operating system requirements for esbuild binaries. For Linux, a kernel version of 3.2 or later is now required.
  Fix: Ensure the underlying Linux operating system meets the minimum kernel version requirements. For specific `Uint8Array.fromBase64` usage with Node, you might need to specify a target like `--target=node22` if not on Node v25+.

Install

• npm install esbuild-linux-64 npm
• yarn add esbuild-linux-64 yarn
• pnpm add esbuild-linux-64 pnpm

Imports

• build
  wrong:

  import { build } from 'esbuild-linux-64'

  correct:

  import { build } from 'esbuild'

  This package (`esbuild-linux-64`) is a native binary and is NOT directly imported into JavaScript/TypeScript code. Users interact with the high-level `esbuild` package, which orchestrates the use of the appropriate platform-specific binary at runtime. Do not attempt to import from `esbuild-linux-64` directly.
• context
  wrong:

  const context = require('esbuild-linux-64');

  correct:

  import { context } from 'esbuild'

  The `context` API is used for incremental builds and watch mode. All programmatic interactions with esbuild, including context creation, are done through the main `esbuild` package. Avoid CommonJS `require` if targeting ESM or using modern Node.js environments.
• serve
  wrong:

  const { serve } = require('@esbuild/linux-x64');

  correct:

  import { serve } from 'esbuild'

  The `serve` API provides a development server. As with other esbuild APIs, it is exposed by the main `esbuild` package, not the platform-specific binary package. Incorrectly trying to `require` the binary package directly will result in a 'Cannot find module' error.

Quickstart

Demonstrates a basic esbuild bundling and minification process using its JavaScript API, highlighting how the main `esbuild` package abstracts away platform-specific binaries like `esbuild-linux-64`.

import { build } from 'esbuild';
import { readFileSync, writeFileSync } from 'fs';
import { resolve } from 'path';

const entryPoint = resolve(__dirname, 'src/index.ts');
const outFile = resolve(__dirname, 'dist/bundle.js');

async function runBuild() {
  try {
    await build({
      entryPoints: [entryPoint],
      bundle: true,
      minify: true,
      sourcemap: true,
      platform: 'node',
      target: 'es2020',
      outfile: outFile,
      logLevel: 'info',
      // This is crucial: esbuild-linux-64 is an *optional dependency* of 'esbuild'.
      // 'esbuild' detects your platform and uses the correct binary.
      // You typically just install 'esbuild' and it handles the rest.
    });
    console.log(`Build successful: ${outFile}`);
    
    // Example of reading the output for verification
    const bundledCode = readFileSync(outFile, 'utf-8');
    console.log(`Bundled code starts with:\n${bundledCode.substring(0, 100)}...`);

  } catch (error) {
    console.error('Build failed:', error);
    process.exit(1);
  }
}

// To make this runnable, ensure a dummy src/index.ts exists:
// mkdir -p src && echo 'console.log("Hello from esbuild!");' > src/index.ts

runBuild();