@jgoz/esbuild-plugin-livereload

@jgoz/esbuild-plugin-livereload

An esbuild plugin that reloads the browser window after you make changes. CSS-only changes are hot reloaded (i.e., without a full page refresh) by default.

Features

• Reloads the browser window when new JS assets are emitted
• Hot-reloads CSS files (configurable) without flashes of unstyled content
• Adds a dismissable error/warning overlay for esbuild output
  • Can be used by other plugins by importing the notify function

How is this different from esbuild's built-in livereload (0.17.0+)?

• Doesn't require use of esbuild's serve() API
• Doesn't require any extra code — client script is injected into the bundle
• Includes an overlay for displaying error messages in the browser

Install

$ npm i @jgoz/esbuild-plugin-livereload

Usage

Add it to your esbuild plugins:

const esbuild = require('esbuild');
const { livereloadPlugin } = require('@jgoz/esbuild-plugin-livereload');

await esbuild.build({
  // ...
  plugins: [livereloadPlugin()],
});

Note that this will have no effect for Node programs.

Plugin API

function livereloadPlugin(options?: LivereloadPluginOptions): Plugin

Plugin options:

Name	Type	Default	Description
fullReloadOnCssUpdates	boolean	false	Instead of hot-reloading CSS files, trigger a full page reload when CSS is updated.
host	string	127.0.0.1	Host that the livereload server will run on. Setting this value to '0.0.0.0' will allow external connections, e.g., when running the livereload server on a different system from the connecting web browser. This setup likely requires setting urlHostname to the either the IP address or local DNS name of the livereload system.
port	number	53099	Port that the livereload server will run on.
urlHostname	string	-	Hostname to use when connecting to the livereload server. This option might be useful when running the livereload server on a different system from the connecting web browser. Defaults to the value specified in host.

Notification API

If you are implementing an esbuild plugin that can emit its own errors or warnings, you may add this package as an optional peerDependency and use the notify function to send those messages to the error overlay.

function notify(errorSource: string, msg: ClientMessage): void

Notifies connected clients that errors or warnings occurred from a given source. If there are no errors and the notification originates from esbuild, the page will be sent a reload request.

Name	Type	Default	Description
errorSource (*)	string	-	Key to use when identifying these errors and warnings. Previous results will be overwritten for the same errorSource.
msg (*)	ClientMessage	-	Object containing errors and warnings from the given source
connectedClients	Set<ServerResponse<IncomingMessage>>	clients	Set of long-lived server responses representing clients currently connected to the livereload server. Only required if you are implementing your own livereload server.

ClientMessage

Name	Type	Default	Description
added (*)	readonly string[]	-	Output files that were added since the last build.
removed (*)	readonly string[]	-	Output files that were removed since the last build.
updated (*)	readonly string[]	-	Output files that were changed since the last build.
errors	readonly Message[]	-	Error messages.
forceReload	boolean	-	Reload the page even if a hot update is possible.
warnings	readonly Message[]	-	Warning messages.