esbuild: JavaScript/CSS Bundler (Linux RISC-V 64-bit)

Common errors

• Error: Cannot find module 'esbuild/lib/main' (or similar path)

  cause The native esbuild binary for your platform was not correctly installed or could not be found, often due to network issues during installation or incorrect npm flags.
  fix Ensure you have a stable internet connection. Try running `npm install esbuild` without `--no-optional` or `--ignore-scripts`. If issues persist, manually verify the `@esbuild/<platform>` package is present in `node_modules` for your OS and architecture.

• ✘ [ERROR] Could not resolve "some-module" (src/index.js:3:19)

  cause esbuild could not locate the imported module. This usually means the module is not installed, misspelled, or esbuild's module resolution rules are not configured correctly for your project structure or specific module type.
  fix Verify the module is installed via `npm install` or `yarn add`. Check for typos in the import path. If it's a Node.js built-in, add it to `external` options. For complex resolutions, consider `alias` or `plugins` for custom handling.

• ✘ [ERROR] Expected ";" but found "}" (src/index.js:10:1)

  cause A syntax error exists in your source code, preventing esbuild from parsing it correctly.
  fix Review the indicated file and line number. Ensure your JavaScript/TypeScript code adheres to correct syntax for the targeted ES version. Use a linter (e.g., ESLint) to catch syntax errors proactively.

• The "esbuild" command must be run with Node.js version 12 or higher.

  cause The installed Node.js version does not meet the minimum requirement specified by esbuild's `engines` field (`"node": ">=12"`).
  fix Upgrade your Node.js environment to version 12 or higher. Use a Node Version Manager (nvm, fnm, volta) to easily switch and manage Node.js versions.

Warnings

• breaking esbuild `v0.27.0` (and later minor releases) introduced deliberate backwards-incompatible changes, including updated Go compiler requirements impacting minimum Linux kernel and macOS versions. Always pin the exact version of `esbuild` in your `package.json` (e.g., `"esbuild": "0.27.0"`) or use a caret range that accepts only patch upgrades (`^0.26.0`, `~0.26.0`) to avoid unexpected breakages.
  Fix: Update your `package.json` to pin `esbuild` to a specific version or use a patch-only range (e.g., `"esbuild": "~0.26.0"`) to ensure consistent builds across deployments. Review the `esbuild` changelog before upgrading major/minor versions to understand potential impact.
• gotcha esbuild is built in Go and relies on native executables for performance. Platform-specific binaries (like `esbuild-linux-riscv64`) are typically installed as optional dependencies. Issues can arise if the correct binary cannot be found or installed, or if npm flags like `--no-optional` or `--ignore-scripts` are used during installation, hindering esbuild's ability to download its binary fallback.
  Fix: Ensure that `--no-optional` and `--ignore-scripts` are not used during `npm install esbuild`. If issues persist, manually ensure the correct `@esbuild/<platform>` package is installed or verify network access to `registry.npmjs.org` for fallback downloads. Check for relevant operating system requirements as `esbuild` updates its Go compiler.
• gotcha Unlike many other bundlers (e.g., Webpack), esbuild does not support external configuration files like `webpack.config.js`. All configurations must be passed either via command-line arguments or programmatically through its JavaScript/TypeScript API.
  Fix: Refactor build configurations into a dedicated JavaScript or TypeScript build script (e.g., `build.js` or `esbuild.config.ts`) using the `esbuild.build()` API, or manage all options directly via CLI flags. Plugins are only supported with the programmatic `build` API.
• gotcha When bundling for Node.js, built-in Node.js modules (like `fs`, `path`, `http`, `https`) are not automatically excluded and will result in build errors like `Could not resolve "https"`.
  Fix: Explicitly mark Node.js built-in modules as external using the `external` option in your `build` configuration or via CLI (`--external:module-name`) to prevent esbuild from trying to bundle them. Also ensure `platform: 'node'` is set for Node.js targets.
• gotcha esbuild's TypeScript loader performs transpilation only; it does not do type-checking. Type errors will not cause an esbuild build to fail, potentially leading to runtime issues.
  Fix: Integrate a separate TypeScript type-checker (like `tsc --noEmit`) into your build pipeline alongside esbuild. Run type-checking as a distinct step, usually before or in parallel with the esbuild compilation, to catch type errors early.

Install

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

Imports

• build
  wrong:

  const { build } = require('esbuild')

  correct:

  import { build } from 'esbuild'

  While `require` works for CommonJS, `esbuild`'s build function is asynchronous and returns a Promise, making `import` with `await` the preferred modern pattern, especially for plugin usage.
• transform
  wrong:

  const transform = require('esbuild').transform

  correct:

  import { transform } from 'esbuild'

  The `transform` API is used for in-memory code transformation and does not support plugins or bundling. It is ideal for minifying or transpiling single code strings.
• BuildOptions

  import type { BuildOptions } from 'esbuild'

  For TypeScript projects, import types separately to define build configurations without bundling them into the output.

Quickstart

This quickstart demonstrates how to programmatically use esbuild to bundle a TypeScript project, including creating dummy source files, handling imports, and configuring common build options like minification, source maps, and output format for Node.js. It shows the asynchronous `build` API and basic error handling.

import { build } from 'esbuild';
import { readFileSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';

const entryPoint = join(process.cwd(), 'src/main.ts');
const outputDir = join(process.cwd(), 'dist');
const outputFile = join(outputDir, 'bundle.js');

const content = `
  // src/main.ts
  import { add } from './utils';
  console.log('Hello from esbuild!');
  const result = add(5, 3);
  console.log('5 + 3 =', result);
`;

const utilsContent = `
  // src/utils.ts
  export function add(a: number, b: number): number {
    return a + b;
  }
`;

// Create dummy source files for demonstration
writeFileSync(entryPoint, content);
writeFileSync(join(process.cwd(), 'src/utils.ts'), utilsContent);

// Ensure output directory exists
import { mkdirSync } from 'node:fs';
mkdirSync(outputDir, { recursive: true });

async function runBuild() {
  try {
    await build({
      entryPoints: [entryPoint],
      bundle: true,
      outfile: outputFile,
      platform: 'node',
      format: 'esm',
      target: 'es2022',
      minify: true,
      sourcemap: true,
      logLevel: 'info',
      external: ['node:fs', 'node:path'], // Mark Node.js built-ins as external
    });
    console.log('Build successful!');
    const bundledCode = readFileSync(outputFile, 'utf-8');
    console.log('\n--- Bundled Code (truncated) ---');
    console.log(bundledCode.substring(0, 500) + '...');
  } catch (e) {
    console.error('Build failed:', e.message);
    process.exit(1);
  }
}

runBuild();