esbuild Debug Tools

0.0.10 verified Fri May 01 auth: no javascript

A tiny helper library (v0.0.10, early stage, monthly releases) that provides a WatchPlugin to monitor esbuild builds and a startDebugServer to run a local debug server with path rewriting. Differentiates by offering zero-config console logging for build results and a simple API proxy to avoid CORS issues. Requires esbuild ^0.19.2, ships TypeScript definitions. No live reload built-in.

Common errors

error Error: Cannot find module 'esbuild-debug-tools' ↓

cause Package not installed or import path incorrect.

fix

Run 'npm install esbuild-debug-tools' and verify import statements use named exports: import { WatchPlugin } from 'esbuild-debug-tools'.

error TypeError: esbuild_debug_tools_1.WatchPlugin is not a function ↓

cause Attempted to use default import instead of named import.

fix

Use named import: import { WatchPlugin } from 'esbuild-debug-tools'.

error Error: The service is not available (esbuild >= 0.17.10 required) ↓

cause Installed esbuild version is too old.

fix

Update esbuild to ^0.19.2: 'npm install esbuild@^0.19.2'.

Warnings

gotcha No live reload: you must provide your own livereload plugin or manually refresh the browser. ↓

fix Use a separate livereload plugin or reload page manually.

breaking Requires esbuild >=0.17.10, but peer dependency specifies ^0.19.2. Using older esbuild may cause runtime errors. ↓

fix Ensure esbuild version meets at least 0.17.10, preferably ^0.19.2.

gotcha WatchPlugin will print to console if no config is provided; this may be unexpected in production. ↓

fix Always pass an onEnd handler to silence default logging.

Install

npm install esbuild-debug-tools

yarn add esbuild-debug-tools

pnpm add esbuild-debug-tools

Imports

WatchPlugin

wrong

const WatchPlugin = require('esbuild-debug-tools').WatchPlugin

correct

import { WatchPlugin } from 'esbuild-debug-tools'

ESM-only; use named import. Also works with TypeScript as types are shipped.

startDebugServer

wrong

import esbuildDebugTools from 'esbuild-debug-tools'

correct

import { startDebugServer } from 'esbuild-debug-tools'

There is no default export; must use named import.

Quickstart

Shows how to import WatchPlugin for build hooks and startDebugServer for a local debug server with API path rewriting.

import { startDebugServer, WatchPlugin } from 'esbuild-debug-tools';

// Use WatchPlugin in esbuild context
const watchPlugin = WatchPlugin({
  onStart: () => console.log('Build started'),
  onEnd: (result) => console.log('Build finished', result)
});

// Start debug server
startDebugServer({
  debugPort: 8080,
  htmlPagePath: './dist/index.html',
  apiPathRewrite: {
    original: '/api/',
    alias: 'https://api.example.com/'
  }
});

console.log('Debug server running on port 8080');