esbuild Windows 64-bit Binary

Common errors

• Error: Command failed: /usr/local/bin/node /path/to/node_modules/esbuild/bin/esbuild --version\nSyntaxError: Invalid or unexpected token

  cause This typically indicates a corrupted esbuild binary or an incorrect installation, potentially due to an on-premise npm registry serving a malformed package, or trying to run a binary compiled for a different architecture/OS.
  fix Reinstall `esbuild` (and its optional platform-specific binaries) on the correct operating system and architecture. Check if your npm registry or proxy might be corrupting downloaded packages. Ensure you're using the correct Node.js version and architecture.

• ✘ [ERROR] Could not resolve "some-module" src/index.js:3:19:

  cause esbuild cannot locate the module specified in an import or require statement, often due to a missing package in `node_modules`, a typo in the module name, or an incorrect import path.
  fix Verify that the module is installed (e.g., `npm install some-module`). Ensure the module name and path are spelled correctly, and that your `node_modules` is accessible and contains the dependency. Check for any specific loader or plugin configurations required for that module.

• ✘ [ERROR] Expected ";" but found "}" src/app.ts:10:1:

  cause A syntax error in your source code (TypeScript, JavaScript, JSX, or CSS) prevents esbuild from parsing and transforming the file correctly.
  fix Examine the file and line number indicated in the error message. Correct any syntax mistakes. Utilizing linters like ESLint or your IDE's built-in syntax checking can help catch these errors pre-build.

• "foo/bar.js" is not exported from package "foo"

  cause This error occurs when a package uses subpath patterns in its `package.json` `exports` field which esbuild may not fully support for resolution, or when attempting to import a non-explicitly exported subpath.
  fix Adjust the import path to match an explicitly exported entry point from the package's `package.json` `exports` field, or raise an issue with the package maintainer if their `exports` patterns are not resolving as expected by esbuild.

• Windows Installation Issue: @esbuild/win32-x64 fails when installed alongside other packages for an application.

  cause This is often related to permissions issues during installation on Windows, particularly when running npm/yarn in an elevated (administrator) terminal or due to conflicts with other concurrently installing packages.
  fix Try running `npm install` in a non-administrator command prompt. If the issue persists, try installing `@esbuild/win32-x64` by itself first (`npm install @esbuild/win32-x64`), then installing other project dependencies. Ensure no other processes are locking files in the `node_modules` directory.

Warnings

• breaking esbuild v0.27.0 introduced backwards-incompatible changes, specifically with the use of `Uint8Array.fromBase64` for binary loading. Projects pinning older versions or using broad semver ranges might encounter issues if this new API is not available in their target environment.
  Fix: Pin your esbuild version using `--save-exact` or update your project's target environment to support `Uint8Array.fromBase64`. It is recommended to pin the exact version of `esbuild` to avoid unexpected breaking changes.
• breaking esbuild v0.28.0 introduced integrity checks to fallback binary download paths. While enhancing security, this was a breaking change. Additionally, an update to the Go compiler might lead to subtle behavioral differences in edge cases due to changes in garbage collection, memory allocation, and executable format.
  Fix: Ensure your environment allows esbuild to perform integrity checks during fallback downloads. Thoroughly test your build process after upgrading to `v0.28.0` or later due to potential Go compiler changes.
• gotcha Copying `node_modules` directories between different operating systems or architectures (e.g., Windows to Linux Docker, macOS x86-64 to ARM via Rosetta) will cause `esbuild` to fail because it installs platform-specific native binaries. The `esbuild-windows-64` package is one such binary.
  Fix: Do not copy `node_modules`. Instead, ensure `npm install` (or equivalent) is run on the target platform after cloning the repository. For ARM Macs running x86-64 Node.js via Rosetta, ensure you use the ARM version of Node.js or consider the `esbuild-wasm` package (with noted performance penalty).
• gotcha Installing `esbuild` with `--omit=optional` or `--no-optional` flags can prevent the platform-specific binary (like `esbuild-windows-64`) from being correctly installed, leading to the `node_modules/.bin/esbuild` command being missing or non-functional.
  Fix: Avoid using `--omit=optional` or `--no-optional` when installing `esbuild`. The default `npm install esbuild` command is designed to correctly handle optional dependencies for platform-specific binaries.
• gotcha While `esbuild-wasm` offers a cross-platform solution, it comes with a significant performance cost, often being 10 times slower than the native `esbuild` package. Using `esbuild-wasm` as a general solution for native performance issues is not recommended.
  Fix: Prefer the native `esbuild` package whenever possible for optimal performance. Only use `esbuild-wasm` if absolute cross-platform compatibility is required and the performance degradation is acceptable for your use case.

Install

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

Imports

• build
  wrong:

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

  correct:

  import * as esbuild from 'esbuild';
  await esbuild.build({...});

  For ESM projects, use named imports like `import * as esbuild from 'esbuild';`. The CommonJS `require` style is still supported but ESM is generally preferred for new Node.js projects. This package (`esbuild-windows-64`) is *not* directly imported.
• context

  import { context } from 'esbuild';
  const ctx = await context({...});

  The `context` API is used for watch and serve modes, providing a long-running process for incremental builds. It's an asynchronous function.
• transform

  import { transform } from 'esbuild';
  const result = await transform(code, {...});

  The `transform` API is for transforming a single string of code without bundling. Useful for integrating esbuild into other tools or for quick code manipulations.

Quickstart

This quickstart demonstrates how to programmatically use esbuild's `build` API to bundle and minify a TypeScript application targeting Node.js, including JSX transformation and sourcemap generation.

import * as esbuild from 'esbuild';
import path from 'path';
import { fileURLToPath } from 'url';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

const entryPoint = path.join(__dirname, 'src', 'app.ts');
const outputDir = path.join(__dirname, 'dist');

const config = {
  entryPoints: [entryPoint],
  bundle: true,
  minify: true,
  sourcemap: true,
  outfile: path.join(outputDir, 'bundle.js'),
  platform: 'node', // or 'browser', 'neutral'
  format: 'esm', // or 'cjs', 'iife'
  target: 'es2020',
  logLevel: 'info',
  jsx: 'automatic',
  external: ['react', 'react-dom'] // Example: exclude external packages
};

async function buildProject() {
  try {
    await esbuild.build(config);
    console.log('Build successful!');
  } catch (error) {
    console.error('Build failed:', error);
    process.exit(1);
  }
}

buildProject();