@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. |