esbuild Linux PowerPC 64-bit Little Endian Binary

Common errors

• Error: The package "esbuild-..." could not be found, and is needed by esbuild

  cause This usually indicates that esbuild's optional platform-specific binary dependency could not be installed due to incompatible platform, architecture, or `--no-optional` flag during npm install.
  fix Remove `node_modules` and `package-lock.json`, then reinstall without `--no-optional`. Ensure your system's OS and architecture are supported by a native esbuild binary. Update npm if it's an older version.

• npm WARN notsup SKIPPING OPTIONAL DEPENDENCY: Unsupported platform for esbuild-linux-ppc64le@X.Y.Z: wanted {"os":"linux","arch":"ppc64"} (current: {"os":"darwin","arch":"x64"})

  cause This warning occurs when npm attempts to install an architecture-specific esbuild binary that does not match the current operating system or CPU architecture. It often appears when running `npm install` on a different platform than where the lockfile was generated.
  fix This is typically a warning and not an error if the correct binary for the *current* platform is successfully installed. If it prevents esbuild from running, ensure `esbuild` is installed without `--no-optional` and that your `package-lock.json` doesn't exclusively lock to a non-matching platform. Delete `node_modules` and `package-lock.json` and reinstall to allow npm to choose the correct binary for the current system.

• Error: Command failed: /path/to/node_modules/esbuild/bin/esbuild --version

  cause This error means the esbuild executable could not be found or executed, often due to a missing binary, incorrect permissions, or an issue during installation.
  fix Check that the esbuild native binary is present in `node_modules/esbuild/bin/`. Verify its executable permissions. Try deleting `node_modules` and `package-lock.json` and running `npm install` again to ensure a clean installation. If using a custom install script, ensure it correctly handles esbuild's installation.

Warnings

• breaking esbuild v0.27.0 introduced deliberate backwards-incompatible changes. Users are advised to pin exact versions or use patch-only version ranges (e.g., `^0.26.0` or `~0.26.0`) to avoid unexpected breakage from major or minor releases.
  Fix: Review release notes for v0.27.0 and subsequent versions before upgrading. Pin `esbuild` to an exact version in `package.json` (e.g., `"esbuild": "0.28.0"`) or use a tilde `~` prefix for patch-level updates (`"esbuild": "~0.28.0"`).
• gotcha Using `--no-optional` flag with `npm install` can prevent esbuild from installing its platform-specific native binary, leading to errors when esbuild tries to execute. The native binaries are crucial for performance.
  Fix: Avoid using `--no-optional` when installing esbuild. Ensure npm can install optional dependencies. If issues persist, update npm to a recent version, as older npm versions might have had issues with `optionalDependencies`.
• gotcha The `esbuild-wasm` package provides a cross-platform WebAssembly version of esbuild, but it is significantly slower (often 10x slower) than the native executables provided by the `esbuild` package and its platform-specific binary dependencies (like `esbuild-linux-ppc64le`).
  Fix: Always prefer installing the main `esbuild` package unless there's a specific need for the WebAssembly version (e.g., browser-based execution). The `esbuild` package will automatically select and install the correct native binary for your platform.
• gotcha Esbuild's CLI arguments can be subject to shell-specific behavior (e.g., glob expansion). For robust and predictable builds, especially when dealing with complex paths or patterns, using the JavaScript API is recommended.
  Fix: Transition from CLI usage to the JavaScript API (`esbuild.build()` or `esbuild.context()`) for projects requiring reliable and consistent build configurations across different environments.

Install

• npm install esbuild-linux-ppc64le npm
• yarn add esbuild-linux-ppc64le yarn
• pnpm add esbuild-linux-ppc64le pnpm

Imports

• build
  wrong:

  const { build } = require('esbuild')

  correct:

  import { build } from 'esbuild'

  The `build` API is asynchronous and recommended for most bundling tasks. `esbuild` is primarily ESM-first, though CommonJS `require` still works.
• transform
  wrong:

  const { transform } = require('esbuild')

  correct:

  import { transform } from 'esbuild'

  The `transform` API processes a single string of code without file system access, suitable for in-memory transpilation.
• context
  wrong:

  import esbuild from 'esbuild'; esbuild.context

  correct:

  import { context } from 'esbuild'

  Since v0.17, `context` provides an incremental build API for faster rebuilds in development, supporting watch and serve modes. This should be explicitly imported.

Quickstart

This quickstart demonstrates how to use esbuild's `build` API to bundle a TypeScript application, including minification, source maps, and environment variable definition.

import { build } from 'esbuild';

const entryPoint = 'src/app.ts';
const outFile = 'dist/bundle.js';

async function bundleApp() {
  try {
    await build({
      entryPoints: [entryPoint],
      bundle: true,
      minify: true,
      sourcemap: true,
      outfile: outFile,
      platform: 'node',
      target: 'es2022',
      // Define environment variables, e.g., for API keys
      define: {
        'process.env.API_KEY': JSON.stringify(process.env.API_KEY ?? 'your-default-api-key'),
      },
      logLevel: 'info',
      // Optional: watch mode for development
      // watch: {
      //   onRebuild(error, result) {
      //     if (error) console.error('watch build failed:', error);
      //     else console.log('watch build succeeded:', result);
      //   },
      // },
    });
    console.log(`Successfully bundled ${entryPoint} to ${outFile}`);
  } catch (e) {
    console.error(`Bundling failed: ${e.message}`);
    process.exit(1);
  }
}

bundleApp();