@pizca/esbuild-server

An esbuild plugin that creates an HTTP server to enable watch mode with automatic reload on rebuild.

Installation

npm i -D @pizca/esbuild-server

Usage

Import the plugin and add it to your esbuild build configuration:

import esbuild from 'esbuild';
import serverPlugin from '@pizca/esbuild-server';

const isWatching = process.argv.includes('--watch');

esbuild.context({
    entryPoints: ['src/index.ts'],
    bundle: true,
    outdir: 'public/dist',
    plugins: [
        // Other plugins...
        serverPlugin({
            enabled: isWatching, // Enables plugin
            port: 3000, // Optional; defaults to 3000
            root: 'public', // Optional; defaults to 'public'
            mime: { // Custom MIME types; HTML, CSS, and JS are handled by default. 'application/octet-stream' is used as fallback.
                '.webp': 'image/webp',
            },
            onRequest(req, res) {
                if (req.url.split('?')[0] === '/') {
                    res.writeHead(200, { 'content-type': 'text/plain' });
                    res.end('Hello, World!');
                }
            },
        })
    ]
}).then(async (ctx) => {
    return isWatching
        ? ctx.watch().then(() => console.log('👀 Watching...\n'))
        : ctx.rebuild().finally(() => ctx.dispose());
});

You can optionally insert the reload banner into a single output file, even when using multiple JavaScript entry points. Simply provide a file path or a custom handler via the setReloadBanner option.

What it does

This plugin launches a lightweight HTTP server serving files from your specified root directory and injects a client-side script that listens for rebuild events via Server-Sent Events (SSE). When a rebuild completes successfully, the browser reloads automatically.

It supports:

• Serving static files (HTML, JS, CSS, and custom MIME types)
• Live reload on rebuild success
• SSE connection management for multiple clients