esbd

3.3.11 verified Fri May 01 auth: no javascript

CLI wrapper that turns esbuild config files into commands with enhanced developer experience for browser and Node applications. Version 3.3.11 (stable), pairs with esbuild >=0.25.0. Unlike Vite or Parcel which use esbuild only as a transpiler, esbd delegates to esbuild's bundler for 10-100x speed and adds live-reload, HTML entry points, sideband type checking, in-browser error overlay, and asset copying without sacrificing performance. Does not support HMR or unbundled dev. Ships TypeScript types and supports JS plugins. Monthly releases on GitHub.

Common errors

error ReferenceError: require is not defined in ES module scope, you can use import instead ↓

cause Using CJS require() with an ESM-only package (v3+)

fix

Change to import { configure } from 'esbd' or switch to CommonJS if using an older version (v2)

error The 'esbuild' peer dependency is not installed. Install it using 'npm install esbuild' ↓

cause Missing or incompatible esbuild version (must be >=0.25.0)

fix

Run npm install -D esbuild@latest (must be >=0.25.0)

error Error: No entry points specified. Provide at least one entry point in configure({ entryPoints: [...] }) ↓

cause Missing entryPoints property in the config object

fix

Add entryPoints: ['./index.ts', './index.html'] to your configure call

error TypeError: esbd is not a function ↓

cause Trying to call default export (e.g., `const esbd = require('esbd')`) which does not exist; must use named import

fix

Use import { configure } from 'esbd' instead

Warnings

breaking v3.x is ESM-only. CJS require() will not work. ↓

fix Convert to ES modules by setting 'type': 'module' or using .mjs extension, and use import syntax.

breaking Peer dependency esbuild must be >=0.25.0. Older versions will fail at runtime. ↓

fix Update esbuild to >=0.25.0: npm install esbuild@latest

deprecated The 'bundle' config option was removed. Use 'configure' instead. ↓

fix Replace .bundle(...) calls with configure({...}) and pass the same options object.

gotcha HTML entry points require the file to be named with .html extension and contain a <script> tag referencing a valid JS/TS entry. Otherwise build may silently produce empty output. ↓

fix Ensure your HTML file includes a <script type="module" src="./main.ts"> or similar.

gotcha In-browser error overlay requires `serve` mode. Using `node-dev` mode will not show overlay for runtime errors. ↓

fix For browser apps, use `configure({ serve: { port: 8080 } })` and serve over HTTP.

gotcha Sideband type checking runs tsc under the hood; if your tsconfig is misconfigured, it may produce false positives or fail silently. ↓

fix Ensure tsconfig.json has `compilerOptions.noEmit: true` and `compilerOptions.isolatedModules: true` for compatibility.

Install

npm install esbd

yarn add esbd

pnpm add esbd

Imports

configure
wrong
```
const { configure } = require('esbd')
```
correct
```
import { configure } from 'esbd'
```
ESM-only since v3; use import syntax even if package type is commonjs

createServer

wrong

const createServer = require('esbd').createServer

correct

import { createServer } from 'esbd'

Use for programmatic server creation in Node scripts

typeCheck
```
import { typeCheck } from 'esbd'
```
Optional function for sideband TypeScript type checking using tsc

Quickstart

Creates a CLI script that builds an HTML entry point with live-reload and optional type checking.

#!/usr/bin/env node
import { configure } from 'esbd';

configure({
  entryPoints: ['./index.html'],
  absWorkingDir: __dirname,
  outdir: './build',
  // Optional: enable live-reload for web apps
  serve: {
    port: 3000,
    onRequest: (req, res) => {
      console.log(req.url);
    }
  },
  // Optional: sideband type checking
  typeCheck: true
});

console.log('Running esbd...');