esbuild-c

0.1.37 verified Fri May 01 auth: no javascript

esbuild-c (v0.1.37) enhances esbuild with config processing capabilities: aligning CLI options with the JS API, supporting config merging via 'extends', and loading configs in various formats (JSON, YAML, JS, TS) using cosmiconfig. As a PoC, it addresses esbuild issue #884 (CLI plugin specification) and offers both CLI and programmatic usage. It requires esbuild >=0.19.0 and ships TypeScript types. Unlike alternatives like esbuild-config or esbuild-resolve-config, it focuses on extendable config merging and format flexibility.

Common errors

error Error: Cannot find module 'esbuild-c' ↓

cause Package not installed or ESM not fully configured.

fix

Ensure esbuild-c and esbuild are installed: npm i -D esbuild-c esbuild. For ESM, set "type": "module" in package.json or use .mjs extension.

error SyntaxError: Cannot use import statement outside a module ↓

cause Running import syntax in a CommonJS file without ESM configuration.

fix

Use dynamic import: const { loadConfig } = await import('esbuild-c'); or switch to ESM.

error TypeError: loadConfig is not a function ↓

cause Incorrect import (e.g., default import instead of named import).

fix

Use named import: import { loadConfig } from 'esbuild-c'.

Warnings

gotcha Package is PoC (Proof of Concept) - API may change between minor versions. ↓

fix Pin exact version and monitor GitHub releases for breaking changes.

gotcha Config resolution uses cosmiconfig, which searches for 'esbuild' config key in package.json or dedicated files (e.g., esbuild.config.js). Unexpected configs may be loaded. ↓

fix Specify an explicit --config path to avoid accidental loading.

gotcha CLI plugin specification via --plugin flag may require additional setup (see esbuild issue #884). ↓

fix Use plugin paths or register plugins programmatically.

Install

npm install esbuild-c

yarn add esbuild-c

pnpm add esbuild-c

Imports

loadConfig

wrong

const { loadConfig } = require('esbuild-c')

correct

import { loadConfig } from 'esbuild-c'

ESM-only since v0.1.x; use dynamic import for CommonJS

parseArgv

wrong

import { parseArgv } from 'esbuild-c' // correct; no wrong pattern commonly seen

correct

import { parseArgv } from 'esbuild-c'

Parses CLI arguments into esbuild build options

default (CLI runner)
wrong
```
import * as esbuildC from 'esbuild-c'
```
correct
```
import esbuildC from 'esbuild-c'
```
Default export is the CLI function; not commonly imported directly

Quickstart

Shows how to use esbuild-c programmatically: parse CLI args, load config, merge, and build with esbuild.

// CLI usage: npx esbuild-c --config esbuild.config.js

// Programmatic usage (ESM)
import esbuild from 'esbuild';
import { loadConfig, parseArgv } from 'esbuild-c';

const flags = parseArgv(process.argv.slice(2));
const config = await loadConfig({
  // optional overrides: cwd, stopDir, searchPlaces
});

// Merge flags into config (flags have precedence)
const merged = { ...config, ...flags };

await esbuild.build(merged);