esbuild Darwin ARM 64-bit Binary

Common errors

• Error: No esbuild binary found for darwin/arm64. Please install the "esbuild" package manually.

  cause The native esbuild binary for the detected platform and architecture (macOS ARM 64-bit) is missing or cannot be located by the `esbuild` package, often due to an incomplete installation or caching issue.
  fix Ensure you have the main `esbuild` package installed correctly. If issues persist, try `npm rebuild esbuild`, `yarn cache clean && yarn install`, or manually install the correct platform package (e.g., `npm install esbuild-darwin-arm64`). Check if `npm_config_esbuild_binary_path` environment variable is misconfigured.

• TypeError: esbuild.build is not a function

  cause Incorrect import statement (e.g., default import when only named exports exist, or trying to use `require()` on a module that is primarily ESM and not correctly shimmed for CJS).
  fix For ES Modules, use `import { build } from 'esbuild';`. For CommonJS, use `const esbuild = require('esbuild');` and then `esbuild.build(...)`. Ensure your `tsconfig.json` and `package.json` (`"type": "module"`) are correctly configured for your chosen module system.

• SyntaxError: Cannot use import statement outside a module

  cause Attempting to use ES module syntax (e.g., `import`, `export`) in a JavaScript file that is being interpreted as a CommonJS script. This is common when `"type": "module"` is missing in `package.json` or incorrect file extensions are used.
  fix To enable ES module syntax, add `"type": "module"` to your `package.json`. Alternatively, rename your file to use a `.mjs` extension for ES modules or `.cjs` for CommonJS. If using Node.js, ensure your version supports ESM.

Warnings

• breaking esbuild v0.27.0 introduced backwards-incompatible changes. Users should always pin the exact version of `esbuild` in `package.json` (e.g., `"esbuild": "0.27.0"`) or use patch-only version ranges (e.g., `^0.27.0` or `~0.27.0`) to avoid unexpected breakage from minor or major updates. Always review `esbuild`'s release notes for specific migration guides.
  Fix: Update `package.json` to pin `esbuild` to an exact version or use a `~` range. Carefully review the changelog for affected versions and apply necessary code changes.
• gotcha This `esbuild-darwin-arm64` package is a platform-specific binary component. Its version (`0.15.18` provided) might not directly correspond to the latest `esbuild` npm package version (which is currently around `0.28.x` based on the changelog). Installing the main `esbuild` package automatically pulls the correct and compatible binary for your system architecture and `esbuild` version. Direct installation of platform-specific binaries is generally discouraged unless for advanced scenarios, as it can lead to version mismatches or 'No esbuild binary found' errors.
  Fix: Prefer installing the main `esbuild` package, which intelligently selects and installs the correct `@esbuild/*` native binary package as a dependency. Avoid directly managing `esbuild-darwin-arm64` unless specifically required by your build setup.
• gotcha When targeting older JavaScript environments, esbuild performs lowering (transpilation) of modern syntax. An incorrectly configured `target` option can lead to unexpected output or runtime errors if the generated code includes features not supported by the specified environment (e.g., class fields for TypeScript parameter properties without appropriate lowering).
  Fix: Carefully configure the `target` option in `build` or `transform` options to precisely match your deployment environment's actual JavaScript capabilities (e.g., `es2015`, `esnext`, `node14`). For TypeScript, ensure class field lowering is appropriate for the target.
• breaking Changes in parsing and printing CSS media queries, async generator transformation, and support for new import path specifiers (e.g., `#/` aliases) have been introduced across various minor versions. While often bug fixes or feature additions, these can subtly alter output or behavior if strict parsing rules or specific generator/import patterns are relied upon without testing.
  Fix: Thoroughly test your build process after any `esbuild` upgrade, especially if you rely on specific CSS output, complex async generators, or advanced import patterns. Review relevant changelog entries for affected versions to understand changes.

Install

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

Imports

• build
  wrong:

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

  correct:

  import { build } from 'esbuild'

  The primary function for bundling files. `esbuild` is primarily an ESM-first package but supports CommonJS `require()` as well. Use named imports for better tree-shaking and clarity in ESM.
• transform
  wrong:

  import * as esbuild from 'esbuild'; esbuild.transform(...)

  correct:

  import { transform } from 'esbuild'

  Used for transforming individual code strings or files without full bundling. Useful for integrating `esbuild` into other tools or loaders that need AST manipulation or specific transpilation.
• initializePlugin

  import { initializePlugin } from 'esbuild'

  For `esbuild` plugin development in Node.js, this function initializes the plugin system, enabling custom behaviors during the build process. Required for any advanced plugin that interacts with the build lifecycle.
• formatMessages
  wrong:

  import esbuild from 'esbuild'; esbuild.formatMessages(...)

  correct:

  import { formatMessages } from 'esbuild'

  A utility function to format `esbuild` diagnostic messages (errors, warnings) into a human-readable string, useful for custom error reporting in build scripts.

Quickstart

Demonstrates a basic esbuild bundling operation for a TypeScript entry point, including minification, sourcemaps, targeting a specific platform, and a simple plugin example to log build events.

import { build } from 'esbuild';

const entryPoint = 'src/index.ts';
const outputPath = 'dist/bundle.js';

async function main() {
  try {
    const result = await build({
      entryPoints: [entryPoint],
      bundle: true,
      minify: true,
      sourcemap: true,
      outfile: outputPath,
      platform: 'node', // or 'browser', 'neutral'
      target: 'es2020',
      logLevel: 'info',
      plugins: [
        // Example: A simple plugin that logs file paths before the build starts
        {
          name: 'log-paths',
          setup(build) {
            build.onStart(() => {
              console.log(`
Starting esbuild process for: ${entryPoint}`);
            });
            build.onEnd(result => {
              if (result.errors.length === 0) {
                console.log(`Build successful: ${outputPath}`);
              } else {
                console.error('Build failed with errors:', result.errors);
              }
            });
          },
        },
      ],
    });
    console.log('esbuild build operation completed.');
    if (result.warnings.length > 0) {
        console.warn('Warnings:', result.warnings);
    }
  } catch (e) {
    console.error('An unhandled error occurred during build:', e.message);
    process.exit(1);
  }
}

main();