esbuild FreeBSD 64-bit Binary

Common errors

• Error: Cannot find module 'esbuild/lib/main.js' or 'esbuild/lib/main.wasm' or 'esbuild/bin/esbuild'

  cause This error often occurs when the native binary for esbuild (like esbuild-freebsd-64) fails to install correctly or is not found in the expected location, often due to npm permissions or environmental issues.
  fix Ensure `esbuild` and its platform-specific binaries are correctly installed by running `npm rebuild esbuild`. Check your npm cache and ensure sufficient permissions in your project directory. Sometimes, manually deleting `node_modules` and `package-lock.json` then reinstalling (`npm install`) can resolve this.

• TypeError: esbuild.build is not a function

  cause This typically happens when trying to use esbuild's API in a CommonJS environment without correctly importing it as an ESM module, or when a bundler is incorrectly processing esbuild itself.
  fix If in a CommonJS file, use `const esbuild = require('esbuild');` and then `esbuild.build(...)`. If using ESM, ensure `import { build } from 'esbuild';` is at the top of the file and your environment supports ESM.

• ESBUILD_EXIT_CODE: 1

  cause A generic exit code from esbuild indicating a build failure. This is often accompanied by more specific errors in the esbuild output regarding parsing, configuration, or file resolution.
  fix Examine the detailed error messages printed by esbuild in the console. These messages will point to the specific file, line, or configuration issue causing the build to fail. Increase `logLevel` to 'verbose' for more diagnostic output.

Warnings

• breaking The default value for the `target` option changed from `es2015` to `es2016` in esbuild v0.15.0. This might affect generated code compatibility for older environments if you rely on the default.
  Fix: Explicitly set `target: 'es2015'` in your esbuild configuration if you need to support environments that do not support ES2016 features.
• breaking The default value for the `charset` option changed from `ascii` to `utf8` in esbuild v0.15.0. This can alter how non-ASCII characters are handled in output files, potentially causing issues with older systems or specific encoding expectations.
  Fix: If your project specifically requires ASCII output for character encoding, set `charset: 'ascii'` in your esbuild configuration.
• breaking The `jsxFactory` and `jsxFragment` options now correctly accept empty string values starting from esbuild v0.15.0. If you previously relied on their incorrect handling of empty strings, your build behavior may change.
  Fix: Review your `jsxFactory` and `jsxFragment` settings. If an empty string was unintentionally ignored, confirm the new behavior aligns with your desired output.
• gotcha The `esbuild-freebsd-64` package is a specific native binary for `esbuild`. While `esbuild` itself is at `v0.28.x`, this binary package is fixed at `v0.15.18`. For new projects, install the main `esbuild` package, which will automatically select the correct, up-to-date binary for your platform. Manually installing this specific binary is generally only needed for explicit version control or debugging platform-specific issues.
  Fix: For the latest esbuild features and bug fixes, install `esbuild` directly (`npm install esbuild`). If you must use a specific older version of `esbuild`, ensure the corresponding binary package version is compatible.

Install

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

Imports

• build
  wrong:

  const { build } = require('esbuild')

  correct:

  import { build } from 'esbuild'

  The 'esbuild-freebsd-64' package provides the native binary, but the public API is imported from the main 'esbuild' package. ESM is standard; CJS is also supported.
• transform
  wrong:

  import transform from 'esbuild/lib/transform'

  correct:

  import { transform } from 'esbuild'

  For transforming individual code strings or buffers, use the named `transform` export. Avoid deep imports from `lib/` as they are internal and subject to change.
• FormatMessagesOptions
  wrong:

  import { FormatMessagesOptions } from 'esbuild'

  correct:

  import type { FormatMessagesOptions } from 'esbuild'

  When importing types in TypeScript, use `import type` for clarity and to prevent runtime imports. This type is used with `formatMessages`.

Quickstart

This quickstart demonstrates how to use the esbuild `build` API to bundle a TypeScript file into an optimized ES module for Node.js, including minification and source maps.

import { build } from 'esbuild';
import path from 'path';
import fs from 'fs/promises';

const entryPoint = './src/index.ts';
const outputDir = './dist';

async function buildProject() {
  try {
    await fs.mkdir(outputDir, { recursive: true });
    await fs.writeFile(path.join(path.dirname(entryPoint), path.basename(entryPoint)), `
      console.log('Hello from esbuild!');
      export const foo = 'bar';
    `);

    const result = await build({
      entryPoints: [entryPoint],
      bundle: true,
      outdir: outputDir,
      platform: 'node',
      target: 'es2020',
      minify: true,
      sourcemap: true,
      logLevel: 'info',
      format: 'esm',
    });

    if (result.errors.length > 0) {
      console.error('Build failed with errors:', result.errors);
    } else {
      console.log('Build successful! Output in:', outputDir);
      const outputFile = path.join(outputDir, 'index.js');
      const content = await fs.readFile(outputFile, 'utf-8');
      console.log('\n--- Output Content (truncated) ---\n', content.substring(0, 200), '...');
    }
  } catch (e) {
    console.error('An unexpected error occurred during build:', e);
  }
}

buildProject();