LiveReload JavaScript Client

Common errors

• ReferenceError: window is not defined

  cause 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)

  cause 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

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

Warnings

• gotcha It 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.
• breaking Explicitly 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.
• 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`).
• gotcha This 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.

Install

• npm install livereload-js npm
• yarn add livereload-js yarn
• pnpm add livereload-js pnpm

Imports

• script tag inclusion

  <!-- Add this snippet to your HTML, replacing the host/port as needed -->
  <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
  wrong:

  import LiveReload from 'livereload-js';

  correct:

  window.LiveReloadOptions = { host: 'localhost', port: 35729 };
  require('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.

Quickstart

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.

<!-- index.html -->
<!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>

    <!-- Recommended way to include livereload.js, served by your dev server -->
    <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;
}