esbuild (OpenBSD 64-bit Binary)

Common errors

• Error: No native build was found for platform...

  cause The esbuild package could not find a compatible native binary for your operating system and architecture, or the installed binary is corrupted. This often happens in cross-platform development environments or when `node_modules` is copied between different OS/architectures.
  fix Ensure you are running `npm install esbuild` on the target machine with the correct Node.js version and architecture. Delete `node_modules` and `package-lock.json` and run `npm install` again. For Docker, ensure the `npm install` step runs inside the final container environment. If using a specific `esbuild-platform-arch` package, verify it matches your system.

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

  cause esbuild cannot find an imported module. This can be due to a missing package, incorrect import path, or an external module that esbuild isn't configured to handle.
  fix Verify the module is installed (e.g., `npm install some-module`). Check the import path for typos or case sensitivity. If the module is a Node.js built-in and you're targeting the browser, ensure `platform: 'node'` is set in esbuild options, or mark it as `external` if it should not be bundled.

• Error: [esbuild] Argument 'entryPoints' must be an array

  cause The `entryPoints` option in the `build` configuration was provided with an incorrect type, often a string instead of an array of strings.
  fix Ensure `entryPoints` is an array of strings, even if you only have a single entry point: `entryPoints: ['src/index.ts']`.

Warnings

• breaking esbuild `v0.27.0` (and other pre-1.0 versions) included deliberate backwards-incompatible changes. The project recommends pinning the exact version in `package.json` or using a version range that only accepts patch upgrades (e.g., `^0.26.0` or `~0.26.0`) to avoid unexpected breakages.
  Fix: Always pin exact versions (`"esbuild": "0.28.0"`) or use patch-only version ranges (`"esbuild": "~0.28.0"`) in `package.json` to prevent automatic major-like updates that may contain breaking changes.
• gotcha This package (`esbuild-openbsd-64`) is a platform-specific binary. For general use, you should typically install the main `esbuild` package, which automatically selects and installs the correct platform binary for your system. Directly installing platform-specific packages is only needed in advanced scenarios, like when managing multiple target platforms in a single environment.
  Fix: Install `esbuild` directly via `npm install esbuild`. Only use `@esbuild/platform-arch` packages if you explicitly need to manage platform-specific binaries for cross-compilation or specific deployment targets.
• gotcha esbuild's plugin system differs from Webpack/Rollup, relying on 'onLoad' and 'onResolve' callbacks rather than a traditional plugin API. While powerful, this means certain complex transformations or integrations might require a different approach or may not be directly supported as a plugin.
  Fix: Review esbuild's documentation on plugins for 'onLoad' and 'onResolve' hooks. If a specific feature isn't supported by existing plugins, custom logic might be needed, or consider integrating esbuild with other tools for specific transformations.
• breaking Version `0.27.0` raised operating system requirements. For instance, Linux now requires kernel version 3.2+ and macOS 12+ (Monterey). Older systems may fail to run the native binary.
  Fix: Ensure your operating system meets the minimum requirements for the esbuild version you are using. If an upgrade isn't possible, you may need to pin to an older esbuild version or consider `esbuild-wasm` as a less performant but more compatible alternative.

Install

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

Imports

• build
  wrong:

  const { build } = require('esbuild')

  correct:

  import { build } from 'esbuild'

  The `build` function is the primary asynchronous API for bundling files. While CommonJS `require` works, ESM `import` is the modern approach and recommended when possible, especially in TypeScript projects.
• transform

  import { transform } from 'esbuild'

  The `transform` function is used for single-file transformations like minification, TypeScript/JSX compilation, or converting newer JS to older JS, without bundling.
• serve

  import { serve } from 'esbuild'

  The `serve` function provides a local development server with optional watch mode and live reloading capabilities.
• BuildOptions
  wrong:

  import { BuildOptions } from 'esbuild'

  correct:

  import { type BuildOptions } from 'esbuild'

  When importing types like `BuildOptions`, use `import type` for clarity and to ensure they are stripped during compilation.

Quickstart

This quickstart demonstrates a basic TypeScript project bundling and minification using esbuild's JavaScript API. It creates a simple `src` directory with two files, then configures esbuild to bundle them into a minified, sourcemapped output file for the browser.

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

// Create dummy source files for the example
const srcDir = path.join(process.cwd(), 'src');
const distDir = path.join(process.cwd(), 'dist');

if (!fs.existsSync(srcDir)) fs.mkdirSync(srcDir);
if (!fs.existsSync(distDir)) fs.mkdirSync(distDir);

fs.writeFileSync(path.join(srcDir, 'index.ts'), `
  // src/index.ts
  import { greet } from './utils';
  console.log(greet('World from esbuild!'));
`);
fs.writeFileSync(path.join(srcDir, 'utils.ts'), `
  // src/utils.ts
  export function greet(name: string): string {
    return \`Hello, \${name} from esbuild!\`;
  }
`);

async function bundleApp() {
  try {
    console.log('Starting esbuild...');
    const result = await build({
      entryPoints: [path.join(srcDir, 'index.ts')],
      bundle: true,
      minify: true,
      sourcemap: true,
      outfile: path.join(distDir, 'bundle.js'),
      platform: 'browser', // or 'node' depending on target environment
      target: ['es2020', 'chrome88'], // Specify target environments
      logLevel: 'info', // Adjust log verbosity
    });
    console.log('esbuild completed successfully.');
    // Optionally, inspect the output or metadata
    // console.log(result.metafile);
  } catch (error: any) {
    console.error('esbuild failed:');
    if (error.errors) {
      error.errors.forEach((err: any) => console.error(err.text));
    } else {
      console.error(error);
    }
    process.exit(1);
  }
}

bundleApp();