esbuild Linux ARM 64-bit Binary

Common errors

• ✘ [ERROR] Could not resolve "some-module"

  cause esbuild cannot find the specified module. This often happens if the module is not installed, misspelled, or if path resolution is misconfigured.
  fix Verify `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 "}"

  cause This is a general syntax error encountered by esbuild during parsing. It indicates malformed JavaScript or TypeScript code.
  fix Review 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

  cause 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.
  fix Ensure 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.

  cause 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.
  fix When 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.

Warnings

• breaking esbuild'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.
  Fix: Pin 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.
• breaking The 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.
  Fix: Ensure your project's Node.js environment is version 18 or later. Update your `engines` field in `package.json` to reflect this requirement.
• breaking esbuild 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.
  Fix: Review 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.
• gotcha When 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.
  Fix: Add `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.
• gotcha Updates 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.
  Fix: If 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.
• gotcha Using 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.
  Fix: For 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`.

Install

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

Imports

• build
  wrong:

  const esbuild = require('esbuild'); // CJS is supported, but ESM is generally preferred for modern Node.js development and type safety.

  correct:

  import * as esbuild from 'esbuild';
  
  await esbuild.build({
    entryPoints: ['src/app.js'],
    bundle: true,
    outfile: 'dist/bundle.js',
  });

  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
  wrong:

  import { transform } from 'esbuild'; // Incorrect if 'transform' is not a named export directly from 'esbuild'.

  correct:

  import * as esbuild from 'esbuild';
  
  const result = await esbuild.transform('const a = 1;', {
    loader: 'js',
    minify: true,
  });
  console.log(result.code);

  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'.

Quickstart

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);
}