esbuild-reloader

0.4.1 verified Fri May 01 auth: no javascript

An esbuild plugin that automatically reloads the browser page whenever a new build completes in watch mode. Version 0.4.1 is the latest stable release. It works by injecting a WebSocket listener into the bundle and triggering a page reload on rebuild. Unlike general-purpose live reloaders, this plugin is tightly integrated with esbuild's watch mode and does nothing during regular builds. It supports configurable host, port, reconnect timeout, and retry settings. Released on an as-needed cadence with no recent updates.

Common errors

error Error: [plugin: esbuild-reloader] Must be used with watch mode ↓

cause esbuild.build() called without `watch: true`.

fix

Add watch: true to your esbuild build options.

error TypeError: esbuild_reloader_1.default is not a function ↓

cause Using incorrect import style (named import instead of default).

fix

Use import reloader from 'esbuild-reloader' or const reloader = require('esbuild-reloader').

Warnings

gotcha Plugin only works when watch mode is enabled; does nothing in regular builds. ↓

fix Ensure the esbuild build config has `watch: true`.

gotcha Injecting the WebSocket listener may cause browser CSP issues if Content-Security-Policy blocks inline scripts or websocket connections. ↓

fix Adjust CSP to allow 'ws://' connections to the specified host/port.

deprecated The package lacks explicit support for esbuild v0.18+ where watch API changed. May still work but not officially tested. ↓

fix Prefer esbuild's built-in serve mode or use a more actively maintained reload plugin.

Install

npm install esbuild-reloader

yarn add esbuild-reloader

pnpm add esbuild-reloader

Imports

default

wrong

import { reloader } from 'esbuild-reloader'

correct

import reloader from 'esbuild-reloader'

Package exports a default function only. Named import fails.

default

wrong

const { reloader } = require('esbuild-reloader')

correct

const reloader = require('esbuild-reloader')

In CJS, assign the default export directly, not through destructuring.

EsbuildReloaderOptions
```
import type { EsbuildReloaderOptions } from 'esbuild-reloader'
```
TypeScript users can import the options interface by name. This is the only named export.

Quickstart

Sets up esbuild watch mode with esbuild-reloader plugin to auto-reload on rebuild.

import esbuild from 'esbuild';
import reloader from 'esbuild-reloader';

await esbuild.build({
  entryPoints: ['src/index.js'],
  outfile: 'dist/bundle.js',
  bundle: true,
  watch: true,
  plugins: [
    reloader({
      host: '127.0.0.1',
      port: 8001,
      reconnectTimeout: 5000,
      retries: 10
    })
  ]
});