esbuild macOS 64-bit Binary

Common errors

• Error: Cannot find module 'esbuild'

  cause The `esbuild` package is not installed, or the Node.js process cannot resolve it.
  fix Run `npm install esbuild` or `yarn add esbuild` in your project directory. Ensure `esbuild` is listed in your `package.json` dependencies.

• Error: Build failed: [ERROR] Could not resolve "./my-module" (use "--resolve-extensions=.ts,.tsx,.js,.jsx,.json,.mjs,.cjs" to specify custom extensions)

  cause esbuild couldn't find a module because of a missing or incorrect file extension, or an incorrect path.
  fix Verify the module path and extension. You might need to explicitly list common extensions in `resolveExtensions` option, or ensure your `tsconfig.json` paths are correctly configured if using TypeScript aliases.

• Error: The "format" option must be either "cjs" or "esm" when "platform" is "node"

  cause When targeting `platform: 'node'`, esbuild requires an explicit `format` option of either `'cjs'` (CommonJS) or `'esm'` (ES Modules) to disambiguate module output.
  fix Add `format: 'cjs'` or `format: 'esm'` to your esbuild `build` options. Choose based on whether your Node.js project is CommonJS or ES Module-based.

• ReferenceError: require is not defined (when using CJS in an ESM context or vice-versa)

  cause Attempting to use CommonJS `require` syntax in an ES Module context, or ESM `import` in a pure CommonJS context, often due to mismatched `type` in `package.json` or incorrect `format` in esbuild config.
  fix Ensure your `package.json` `type` field matches your intended module system (e.g., `"type": "module"` for ESM). In your esbuild config, set `format: 'esm'` or `format: 'cjs'` to match your target environment. For Node.js, also consider `platform: 'node'`.

Warnings

• breaking esbuild `0.27.0` included deliberate backwards-incompatible changes. Users should pin exact versions or use tilde/caret ranges (e.g., `^0.26.0` or `~0.26.0`) to avoid automatically picking up breaking changes.
  Fix: Review the esbuild changelog for `0.27.0` and higher versions to understand specific breaking changes and update your configuration or code accordingly. Pin esbuild versions in `package.json` for stability.
• breaking As of `esbuild@0.28.0`, integrity checks for fallback binary downloads were added. While intended as an improvement, it was released as a breaking change due to embedding hashes of platform-specific binaries into the top-level `esbuild` package. This also involved an upgrade of the Go compiler from 1.25.7 to 1.26.1, which might introduce subtle behavioral changes in edge cases related to garbage collection and memory allocation.
  Fix: Verify that your `esbuild` installations continue to function as expected. If issues arise, consult the `0.28.0` changelog for potential Go compiler-related differences or issues with integrity checks during installation.
• gotcha esbuild's TypeScript loader performs transpilation but does *not* do type-checking. For type-checking, you should run `tsc` separately or use a tool like `fork-ts-checker-webpack-plugin` if integrating with Webpack.
  Fix: Integrate a separate type-checking step in your build pipeline, such as running `tsc --noEmit` before or after esbuild.
• gotcha Using `import()` expressions in non-ESM output formats (e.g., `cjs`) was previously transformed by esbuild, but `0.27.0` changed this behavior to preserve `import()` expressions. This means `import()` with Node.js is now possible when the output is not ESM, but requires the environment to handle these expressions.
  Fix: If you rely on `import()` expressions, ensure your target environment (e.g., Node.js) correctly handles dynamic `import()` calls in the specified output format. Test your bundled code thoroughly.
• breaking The `0.27.2` release, while not explicitly marked as a breaking change in its summary, introduced a change where `using` declarations inside `switch` clauses, previously supported by esbuild, now result in a syntax error. This aligns with a relaxation in the `package.json` spec for import path specifiers starting with `#/`.
  Fix: Avoid `using` declarations directly within `case` or `default` clauses in `switch` statements. Refactor your code to place them outside or in a block scope to prevent syntax errors.

Install

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

Imports

• build
  wrong:

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

  correct:

  import { build } from 'esbuild'

  The `esbuild-darwin-64` package is a runtime dependency for the main `esbuild` package. Developers typically import the `build` function (and other APIs like `transform`, `serve`, `context`) from the `esbuild` package. CommonJS `require` still works but ESM imports are preferred.
• BuildContext
  wrong:

  import { BuildContext } from 'esbuild'

  correct:

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

  While `BuildContext` is a type/interface, the primary way to get a build context for incremental builds or watch mode is through the `context` function. You do not directly import `BuildContext` as a value.
• Plugin
  wrong:

  import { Plugin } from 'esbuild'

  correct:

  import type { Plugin } from 'esbuild'

  When defining esbuild plugins in TypeScript, `Plugin` is an interface and should be imported as a type (`import type`). This ensures it's stripped from the output JavaScript.

Quickstart

This quickstart demonstrates how to programmatically use esbuild's `build` API to bundle a TypeScript file, apply minification, generate sourcemaps, and define environment variables.

import { build } from 'esbuild';
import path from 'path';
import { fileURLToPath } from 'url';
import { dirname } from 'path';

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

// Create a dummy input file
import fs from 'fs';
const inputTs = `
  interface User { id: number; name: string; }
  const user: User = { id: 1, name: 'Alice' };
  console.log(`Hello, ${user.name}!`);
  export { user };
`;
const inputFilePath = path.join(__dirname, 'src', 'main.ts');
const outputDirPath = path.join(__dirname, 'dist');

fs.mkdirSync(path.join(__dirname, 'src'), { recursive: true });
fs.writeFileSync(inputFilePath, inputTs);

async function runBuild() {
  try {
    await build({
      entryPoints: [inputFilePath],
      bundle: true,
      outdir: outputDirPath,
      platform: 'node',
      format: 'esm',
      target: 'es2022',
      minify: true,
      sourcemap: true,
      logLevel: 'info',
      banner: { js: '// Built with esbuild' },
      define: { 'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV ?? 'development') },
    });
    console.log(`
Build successful! Output in: ${outputDirPath}`);
    console.log('Generated file content:');
    console.log(fs.readFileSync(path.join(outputDirPath, 'main.js'), 'utf-8'));
  } catch (e) {
    console.error('Build failed:', e);
    process.exit(1);
  }
}

runBuild();