esbuild Windows ARM64 Binary

Common errors

• Error: The esbuild binary for your current system is not available

  cause The esbuild package could not find or correctly load the native binary for the detected operating system and architecture, or the binary is corrupted/missing.
  fix Run `npm rebuild esbuild` or `npm install --force esbuild` to re-download and re-install the native binary. Verify your Node.js version meets esbuild's requirements and your system architecture is supported.

• Error: Cannot find module 'esbuild'

  cause The 'esbuild' package is not installed or not resolvable from the current working directory, or `node_modules` is corrupted.
  fix Ensure 'esbuild' is listed in your `package.json` and run `npm install` (or `yarn add esbuild`). If it still fails, try clearing your npm cache with `npm cache clean --force` and then reinstalling.

• esbuild: command not found

  cause The esbuild Command Line Interface (CLI) executable is not in your system's PATH, or esbuild was installed locally and you are trying to run it globally without `npx`.
  fix If esbuild is installed locally, use `npx esbuild [args]` to run it. For global access, install it globally via `npm install -g esbuild` and ensure your system's PATH includes the npm global bin directory.

• Syntax error with modern JavaScript/TypeScript features (e.g., 'Class private fields are not supported in esbuild by default')

  cause esbuild's default target `ECMAScript` version is too old for the syntax used in your source code, or specific experimental features require explicit configuration.
  fix Configure the `target` option in your `esbuild` build process to a newer `ECMAScript` version (e.g., `target: 'esnext'` or `target: ['es2020', 'chrome80']`) to enable support for modern language features.

Warnings

• breaking Version 0.27.0 of esbuild introduced deliberate backwards-incompatible changes. Unintended upgrades across minor or major versions can break builds.
  Fix: Pin the exact version of `esbuild` in `package.json` (e.g., `"esbuild": "0.27.0"`) or use a patch-only version range (`"esbuild": "~0.27.0"`) to prevent automatic minor/major updates. Always review the changelog before upgrading.
• gotcha `esbuild-windows-arm64` is a platform-specific binary dependency, not the main `esbuild` package. Directly managing its version can lead to mismatches with the core `esbuild` API and unexpected build issues.
  Fix: Always install the main `esbuild` package (`npm install esbuild`). It will automatically pull in the correct platform-specific binary for your environment. Avoid direct installation or version pinning of specific binary packages like this one unless you have a very specific advanced use case.
• breaking Before version 0.27.7, esbuild incorrectly generated class fields for TypeScript parameter properties when targeting environments that do not support class fields, potentially leading to runtime errors.
  Fix: Upgrade your `esbuild` dependency to version `0.27.7` or newer to ensure correct lowering of TypeScript parameter properties based on the configured target environment.
• gotcha Versions of esbuild prior to 0.27.4 contained regressions in parsing and printing specific CSS media query syntaxes (e.g., `<media-type> and <media-condition-without-or>`), which could result in incorrect or invalid CSS output.
  Fix: If you are encountering issues with CSS media queries, upgrade `esbuild` to version `0.27.4` or later to benefit from the fixes related to media query handling.
• gotcha A bundler bug existed in versions before 0.27.1 affecting ES modules imported via `require` with top-level `var` declarations inside `if` statements, potentially causing incorrect variable scoping or runtime behavior.
  Fix: Upgrade to `esbuild >=0.27.1` to resolve the bundling issue related to `var` hoisting in specific CommonJS/ESM interop scenarios.

Install

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

Imports

• build
  wrong:

  const build = require('esbuild').build;

  correct:

  import { build } from 'esbuild'

  The primary function for programmatic bundling. ESM is preferred for modern Node.js applications.
• transform
  wrong:

  const { transform } = require('esbuild');

  correct:

  import { transform } from 'esbuild'

  Used for transforming a single string of code without bundling, useful for testing or specific code manipulation.
• * as esbuild
  wrong:

  import esbuild from 'esbuild';

  correct:

  import * as esbuild from 'esbuild'

  esbuild does not export a default, so a namespace import or named imports are required for ESM. CommonJS uses `require('esbuild')` directly.

Quickstart

Demonstrates a basic esbuild setup for bundling a TypeScript project, including minification, source maps, environment variable definition, and a simple plugin.

import { build } from 'esbuild';
import path from 'path';

const entryPoint = 'src/index.ts';
const outputDirectory = 'dist';
const outFile = path.join(outputDirectory, 'bundle.js');

async function buildProject() {
  try {
    await build({
      entryPoints: [entryPoint],
      bundle: true,
      outdir: outputDirectory,
      outfile: outFile,
      platform: 'node', // or 'browser'
      target: 'es2020', // Specify target JavaScript version
      minify: true, // Enable minification
      sourcemap: true, // Generate source maps
      define: { // Define global constants
        'process.env.NODE_ENV': JSON.stringify('production'),
        'process.env.MY_API_KEY': JSON.stringify(process.env.MY_API_KEY ?? ''),
      },
      logLevel: 'info',
      external: ['node-fetch'], // Example of an external dependency not to bundle
      plugins: [
        {
          name: 'log-build',
          setup(build) {
            build.onStart(() => console.log('Starting esbuild build...'));
            build.onEnd(() => console.log('esbuild build finished successfully!'));
          },
        },
      ],
    });
    console.log(`Build successful: ${outFile}`);
  } catch (error) {
    console.error('esbuild build failed:', error);
    process.exit(1);
  }
}

buildProject();