Registry / web-framework / livereload-js

livereload-js

library4.0.2jsnpmunverified

LiveReload.js is the client-side JavaScript implementation of the LiveReload protocol, designed to automatically refresh web browsers during development when file changes are detected by a compatible LiveReload server. The current stable version is 4.0.2, with releases occurring periodically for bug fixes and dependency updates. Unlike many development tools, this package is explicitly *not* recommended for direct installation or bundling by most end-users; instead, it is intended to be served and managed by a LiveReload server (e.g., LiveReload app for Mac, rack-livereload, guard-livereload, grunt-contrib-watch, python-livereload). This approach ensures compatibility and allows for server-specific customizations. It supports live CSS and image reloading, as well as full page reloads for other file types, communicating with the server via WebSockets. It differentiates itself by being solely the client aspect of a larger ecosystem, expecting a server component to drive its functionality.

web-framework http-networking

npm install livereload-js

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · LIVERELOAD-JS

livereload-js

web-frameworkjavascriptv4.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–229 runs

build_error

glibc

node 18–229 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

script tag inclusion

✓  <script>document.write('<script src="http://' + (location.host || 'localhost').split(':')[0] + ':35729/livereload.js"></' + 'script>')</script>

This is the primary and recommended method of 'including' livereload.js, served dynamically by a LiveReload server. The host and port should match your running server.

Browserify/CommonJS require

✓ window.LiveReloadOptions = { host: 'localhost', port: 35729 }; require('livereload-js');

✗ import LiveReload from 'livereload-js';

For npm/Browserify usage, it's typically required as a side-effect, often after configuring global options. It does not export a named or default symbol for direct `import`. This method is generally discouraged for typical web development workflows in favor of server-side injection.

LiveReloadConnect / LiveReloadDisconnect events

✓ document.addEventListener('LiveReloadConnect', () => console.log('LiveReload connected!')); document.addEventListener('LiveReloadDisconnect', () => console.log('LiveReload disconnected.'));

To interact with the running LiveReload client programmatically, listen for these custom DOM events. There is also a `LiveReloadShutDown` event to trigger disconnection.

This HTML snippet demonstrates the most common way to include the `livereload.js` client in a web page, typically injected by a LiveReload server, enabling automatic browser reloading on file changes.

<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>LiveReload Demo</title> <link rel="stylesheet" href="style.css"> </head> <body> <h1>Hello LiveReload!</h1> <p>Watch this page refresh automatically.</p>  <script> // This script snippet is typically injected by a LiveReload server or build tool. // It tries to connect to the LiveReload server, usually on port 35729. // Replace 'localhost' and '35729' if your server uses different settings. document.write('<script src="http://' + (location.host || 'localhost').split(':')[0] + ':35729/livereload.js"></' + 'script>'); </script> </body> </html> /* style.css */ body { font-family: sans-serif; background-color: lightblue; color: #333; } h1 { color: darkblue; }

Debug

Known issues

gotchaIt is strongly recommended to use the `livereload.js` script bundled with your specific LiveReload server/app/tool, rather than installing this package directly via npm or Bower. The server-bundled version is guaranteed to be compatible and may be customized.

fix

Refer to your LiveReload server's documentation for the correct method of client-side integration, which usually involves a simple HTML script tag snippet. Avoid direct `npm install livereload-js` unless you are developing a LiveReload server or have a niche use case.

affects: >=1.0.0

breakingExplicitly leaving the port parameter blank in the script URL (e.g., `?port=`) now derives the port from the host part. In previous versions, this would effectively set the port to 0.

fix

Ensure that if you are dynamically generating the `livereload.js` script URL and intend for a specific port (or the default 35729), you explicitly include it in the `port` query parameter (e.g., `?port=35729`). If you want it to derive from the page's host, leave the `?port=` parameter entirely, or set it to an empty string for the intended effect.

affects: >=4.0.0

gotcha`livereload-js` is a browser-side client and relies on browser globals (`window`, `document`). It will not run directly in a Node.js environment without a browser emulation layer.

fix

Ensure `livereload-js` is only executed in a web browser environment. If integrating with build tools like Browserify, be aware that it expects browser globals. For server-side LiveReload functionality, use a Node.js-based LiveReload server package (e.g., `livereload`).

affects: >=1.0.0

gotchaThis package is a development-time dependency and should not be shipped to production. Its purpose is to facilitate live reloading during local development.

fix

Ensure your build process excludes `livereload.js` from production bundles. When using the HTML script tag injection method, configure your server to only inject it in development environments. Use `npm install --save-dev` or `bower install --save-dev` if installing directly.

affects: >=1.0.0

Errors

Common errors & fixes

ReferenceError: window is not defined

Attempting to run `livereload-js` in a Node.js environment or a non-browser context.

fix

This script is designed for browsers. Ensure it's included in an HTML page or a client-side bundle that executes in a browser environment. If you need server-side LiveReload, use a dedicated Node.js LiveReload *server* package.

Failed to load resource: net::ERR_CONNECTION_REFUSED (or similar connection errors)

The `livereload.js` client script failed to connect to the LiveReload server, often due to the server not running, incorrect host/port configuration, or a firewall blocking the connection.

fix

Verify your LiveReload server is running and listening on the expected port (default 35729). Check the script tag's `src` URL for correct host and port. Ensure no firewalls are blocking connections to the LiveReload port.

LiveReload is not defined

The `livereload.js` script was not loaded or executed successfully before other scripts attempted to interact with its global object (though direct interaction with `LiveReload` global is less common now, it attaches functionality to `window`).

fix

Confirm the `<script>` tag loading `livereload.js` is correctly placed and accessible (e.g., `http://localhost:35729/livereload.js`). Check browser developer tools for network errors during script loading. Ensure there are no JavaScript errors preventing its execution.

Upgrade

Version history

4.0.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

5 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/livereload/livereload-js ↗

packagehttps://www.npmjs.com/package/livereload-js ↗

homepagehttps://livereload.com ↗