{"id":15690,"library":"livereload-js","title":"LiveReload JavaScript Client","description":"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.","status":"active","version":"4.0.2","language":"javascript","source_language":"en","source_url":"git://github.com/livereload/livereload-js","tags":["javascript"],"install":[{"cmd":"npm install livereload-js","lang":"bash","label":"npm"},{"cmd":"yarn add livereload-js","lang":"bash","label":"yarn"},{"cmd":"pnpm add livereload-js","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":null,"symbol":"script tag inclusion","correct":"<!-- Add this snippet to your HTML, replacing the host/port as needed -->\n<script>document.write('<script src=\"http://' + (location.host || 'localhost').split(':')[0] + ':35729/livereload.js\"></' + 'script>')</script>"},{"note":"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.","wrong":"import LiveReload from 'livereload-js';","symbol":"Browserify/CommonJS require","correct":"window.LiveReloadOptions = { host: 'localhost', port: 35729 };\nrequire('livereload-js');"},{"note":"To interact with the running LiveReload client programmatically, listen for these custom DOM events. There is also a `LiveReloadShutDown` event to trigger disconnection.","wrong":null,"symbol":"LiveReloadConnect / LiveReloadDisconnect events","correct":"document.addEventListener('LiveReloadConnect', () => console.log('LiveReload connected!'));\ndocument.addEventListener('LiveReloadDisconnect', () => console.log('LiveReload disconnected.'));"}],"quickstart":{"code":"<!-- index.html -->\n<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n    <meta charset=\"UTF-8\">\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n    <title>LiveReload Demo</title>\n    <link rel=\"stylesheet\" href=\"style.css\">\n</head>\n<body>\n    <h1>Hello LiveReload!</h1>\n    <p>Watch this page refresh automatically.</p>\n\n    <!-- Recommended way to include livereload.js, served by your dev server -->\n    <script>\n        // This script snippet is typically injected by a LiveReload server or build tool.\n        // It tries to connect to the LiveReload server, usually on port 35729.\n        // Replace 'localhost' and '35729' if your server uses different settings.\n        document.write('<script src=\"http://' + (location.host || 'localhost').split(':')[0] + ':35729/livereload.js\"></' + 'script>');\n    </script>\n</body>\n</html>\n\n/* style.css */\nbody {\n    font-family: sans-serif;\n    background-color: lightblue;\n    color: #333;\n}\n\nh1 {\n    color: darkblue;\n}\n","lang":"html","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.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.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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`).","message":"`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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"This package is a development-time dependency and should not be shipped to production. Its purpose is to facilitate live reloading during local development.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"Attempting to run `livereload-js` in a Node.js environment or a non-browser context.","error":"ReferenceError: window is not defined"},{"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.","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.","error":"Failed to load resource: net::ERR_CONNECTION_REFUSED (or similar connection errors)"},{"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.","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`).","error":"LiveReload is not defined"}],"ecosystem":"npm"}