esbuild NetBSD AMD64 Binary

Common errors

• Error: spawnSync ./esbuild ENOENT

  cause The esbuild binary could not be found or executed. This often indicates that the platform-specific binary package failed to install correctly (e.g., due to network issues, corrupted cache, or incompatible platform), or the binary lacks execute permissions.
  fix Check your npm installation logs for errors related to 'esbuild-YOUR_PLATFORM' (e.g., `esbuild-netbsd-64`). Try clearing npm cache (`npm cache clean --force`) and reinstalling esbuild. Ensure the binary has executable permissions (`chmod +x node_modules/esbuild/esbuild`). If on NetBSD, verify Node.js's ability to execute external binaries.

• esbuild: command not found

  cause The `esbuild` command-line executable is not available in your system's PATH. This typically happens when esbuild is installed as a local dependency and you're trying to run it directly from the terminal, or if a global installation failed.
  fix If esbuild is a local dependency, use `npx esbuild ...` or define a script in your `package.json` (e.g., `"build": "esbuild src/index.ts --bundle --outfile=dist/main.js"`). If you intend to use it globally, ensure it was installed with `npm install -g esbuild` and your global npm bin directory is in your PATH.

• Error: "/path/to/project/node_modules/esbuild/lib/main.js" is an ES module file cannot be 'require'd. Instead, change the requiring code to use 'import'

  cause You are attempting to load esbuild's main entry point (which is an ES Module) using Node.js's CommonJS `require()` function from a CommonJS context.
  fix Update your code to use `import { build } from 'esbuild'` and ensure your Node.js project is configured for ES Modules. This typically involves adding `"type": "module"` to your `package.json` file or renaming your consuming file to have a `.mjs` extension.

Warnings

• breaking Version 0.27.0 introduced deliberate backwards-incompatible changes. To prevent unexpected breakage, it is strongly recommended to pin the exact `esbuild` version in `package.json` (e.g., `'esbuild': '0.26.0'`) or restrict updates to patch-level releases using tilde/caret ranges carefully (e.g., `'esbuild': '~0.26.0'` but be aware this might still pull in breaking changes for versions like 0.27.x if used with ^0.26.0).
  Fix: Review the specific release notes for breaking changes before upgrading. Pin exact versions (`"esbuild": "0.27.0"`) or use dependency management tools with lockfiles to control updates.
• gotcha NetBSD is not among Node.js's officially supported platforms. While `esbuild-netbsd-64` provides the necessary binary, its stability and full functionality may vary depending on the specific Node.js installation and patches on the NetBSD system. This is a platform-level consideration, not a direct fault of esbuild itself.
  Fix: Consult NetBSD-specific Node.js documentation or community forums for best practices regarding Node.js compatibility and stability on the platform. Consider using an officially supported platform if guaranteed behavior is critical for your application.
• gotcha Several regressions were identified and fixed in previous versions related to CSS media query parsing and minification. Specifically, versions from `0.25.11` to `0.27.4` might have produced incorrect output or failed to properly handle certain media query structures (e.g., `or` clauses), as well as issues with removal of duplicate rules during minification.
  Fix: Upgrade to esbuild v0.27.5 or a later version to ensure correct handling and minification of CSS media queries.
• gotcha An issue existed where async generators transformed by esbuild did not function correctly when polled concurrently (e.g., using `yield* inner()`), specifically for versions from `0.19.0` until `0.27.5`. This could lead to unexpected runtime behavior.
  Fix: Upgrade to esbuild v0.27.5 or a newer version to resolve the async generator concurrent polling bug.
• gotcha A specific bundler bug in versions prior to `0.27.1` caused incorrect hoisting of `var` declarations that were nested inside an `if` statement, particularly when an ES module was imported using `require` (which wraps it). This could lead to runtime errors.
  Fix: Upgrade to esbuild v0.27.1 or a later version to ensure correct hoisting behavior for `var` declarations in bundled code.

Install

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

Imports

• build
  wrong:

  const { build } = require('esbuild')

  correct:

  import { build } from 'esbuild'

  The esbuild API is predominantly designed for ES Modules. While 'require' may function in some CommonJS environments, direct ESM usage is the idiomatic and recommended approach for modern Node.js projects. Ensure your `package.json` specifies `"type": "module"` or use `.mjs` file extensions for direct ESM imports.
• transform
  wrong:

  import esbuild from 'esbuild'; esbuild.transform

  correct:

  import { transform } from 'esbuild'

  Most esbuild API functions are provided as named exports. There is no default export for the API module, and attempting to destructure functions from a non-existent default import will result in an error.
• buildSync
  wrong:

  import { build } from 'esbuild'; build.sync()

  correct:

  import { buildSync } from 'esbuild'

  The synchronous `buildSync` function is a named export. While useful for CLI tools or specific blocking scenarios, synchronous API calls are generally discouraged for long-running operations in Node.js as they block the event loop. Prefer the asynchronous `build` function when possible.

Quickstart

This quickstart demonstrates how to programmatically use esbuild's `build` API to bundle, minify, transpile TypeScript, generate sourcemaps, and define environment-specific constants for a Node.js target, illustrating a common build setup.

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

const projectRoot = process.cwd();
const entryPoint = path.join(projectRoot, 'src', 'index.ts');
const outFile = path.join(projectRoot, 'dist', 'bundle.js');

async function runBuild() {
  console.log(`Starting build for ${entryPoint}...`);
  try {
    await build({
      entryPoints: [entryPoint],
      bundle: true,
      minify: true,
      sourcemap: true,
      outfile: outFile,
      platform: 'node', // Can be 'browser', 'node', or 'neutral'
      target: ['es2020', 'node18'], // Specify target environments
      logLevel: 'info',
      banner: { js: '// Built by esbuild on ' + new Date().toISOString() },
      define: {
        'process.env.NODE_ENV': '"production"', // Define global constants
        '__APP_VERSION__': '"1.0.0"' // Example custom constant
      },
      external: ['lodash', 'axios'], // Exclude these packages from the bundle
    });
    console.log(`Build successful: ${entryPoint} -> ${outFile}`);
  } catch (error) {
    console.error('Build failed with errors:', error);
    process.exit(1);
  }
}

runBuild();