Tiny LiveReload Fork

Common errors

• Error: listen EADDRINUSE: address already in use :::35729

  cause Another process, or a previous instance of your `tiny-lr-fork` server, is already listening on the specified port (default 35729).
  fix Stop the conflicting process, or configure `tiny-lr-fork` to listen on a different port using the `-p` or `--port` command line option, or by passing a `port` option to `tinylr().listen(port, ...)`.

• WebSocket connection to 'ws://localhost:35729/livereload' failed: Error during WebSocket handshake: Unexpected response code: 404

  cause The `tiny-lr-fork` server is either not running, or its middleware is not correctly mounted in your application stack, leading to the `/livereload` path not being handled.
  fix Ensure your `tiny-lr-fork` server is running. If using it as middleware, verify `app.use(lrserver.middleware({ app: app }));` is correctly placed in your Connect/Express application and the `app` object is the same as the one listening on the port.

• TypeError: app.use() requires a middleware function but got a undefined

  cause This typically occurs when `express.bodyParser()` or `express.query()` are referenced as middleware in older examples, but are either not imported or are deprecated in your version of Express.
  fix For modern Express (4.x+), use `app.use(express.json());` and `app.use(express.urlencoded({ extended: true }));` to handle body and query parsing before the `tiny-lr-fork` middleware.

Warnings

• breaking Version 2.0.0 of tiny-lr-fork, alongside its dependency `livereload-js`, has officially dropped support for Internet Explorer versions 6 through 9. Projects targeting these legacy browsers will experience issues.
  Fix: Upgrade client-side browser versions or ensure your development setup does not require LiveReload functionality for IE6-9.
• gotcha When integrating `tiny-lr` as Connect/Express middleware, it requires query and body parsing middleware to be registered *prior* in the stack for POST requests to `/changed` to work correctly. For modern Express, `express.json()` and `express.urlencoded()` are needed.
  Fix: Ensure `app.use(express.json());` and `app.use(express.urlencoded({ extended: true }));` (or equivalent parsing middleware) are registered *before* `app.use(tinylr.middleware({ app: app }));`.
• gotcha The LiveReload browser extensions (Chrome, Firefox, Safari) by default connect to port `35729`. If you configure `tiny-lr-fork` to listen on a different port, the browser extension will not automatically connect. You will need to manually configure the extension or inject the `livereload.js` script with the correct port.
  Fix: For seamless browser extension integration, run `tiny-lr-fork` on port 35729. If a different port is necessary, manually edit the LiveReload browser extension's settings or use the manual script tag injection method with a `port` attribute in your HTML: `<script src="http://localhost:YOUR_PORT/livereload.js?snipver=1"></script>`.
• gotcha `tiny-lr-fork` is a server that *receives* reload notifications and broadcasts them. It does not include built-in file watching capabilities. You must use an external build tool (e.g., Gulp, Webpack, or a simple `fs.watch` script) to detect file changes and then notify `tiny-lr-fork`.
  Fix: Integrate with a file watcher in your build process. Upon file change detection, send an HTTP request to `http://localhost:35729/changed?files=your_file.css` or a POST request with a JSON payload to the `/changed` endpoint.
• deprecated Previous versions of `tiny-lr-fork` (and its original `tiny-lr` predecessor) had vulnerabilities in the `debug` and `qs` dependencies. While these have been patched in recent releases, it's crucial to stay updated.
  Fix: Always upgrade to the latest stable version of `tiny-lr-fork` to ensure all known security vulnerabilities in its dependencies are addressed. Current stable is >=2.0.0.

Install

• npm install tiny-lr-fork npm
• yarn add tiny-lr-fork yarn
• pnpm add tiny-lr-fork pnpm

Imports

• tinylr
  wrong:

  import tinylr from 'tiny-lr';

  correct:

  const tinylr = require('tiny-lr');

  Primarily a CommonJS package. While Node.js supports ESM, its API is designed for `require()`.
• tinylr.Server
  wrong:

  import { Server as LiveReloadServer } from 'tiny-lr';

  correct:

  const LiveReloadServer = require('tiny-lr').Server;

  The `Server` constructor is exposed directly on the main module export. The main export can also be called as a function `tinylr()` to create a server instance directly.
• tinylr.middleware
  wrong:

  import { middleware as lrMiddleware } from 'tiny-lr';

  correct:

  const lrMiddleware = require('tiny-lr').middleware;

  Used to integrate tiny-lr as a Connect/Express middleware. It should be used after body parsing and query parsing middleware.

Quickstart

This quickstart demonstrates how to set up `tiny-lr-fork` as a standalone LiveReload server integrated with an Express application, listening on the default port 35729. It shows both starting the server and integrating its middleware for handling reload requests, along with an example of a custom route. It also includes `curl` commands to trigger reloads.

const tinylr = require('tiny-lr');
const path = require('path');
const express = require('express');

const PORT = 35729; // Standard LiveReload port for browser extensions
const app = express();

// Initialize tiny-lr server
const lrserver = tinylr();

// Listen for specific requests on the tiny-lr server (optional)
lrserver.on('GET /custom-status', (req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('tiny-lr server is running and custom route works!');
});

// Integrate tiny-lr middleware with Express
// In modern Express, query parsing is built-in, but body-parser might still be needed.
app.use(express.json()); // For POST requests with JSON body
app.use(express.urlencoded({ extended: true })); // For URL-encoded bodies
app.use(lrserver.middleware({ app: app })); // Bind tiny-lr routes to the Express app

// Serve static files (e.g., your project's root)
app.use(express.static(path.resolve('./')));

// Start the Express app and tiny-lr server
app.listen(PORT, function() {
  console.log(`Express app and tiny-lr server listening on port ${PORT}`);
  console.log('Use `curl http://localhost:35729/changed?files=index.html` to trigger reloads.');
  console.log('Or `curl -X POST http://localhost:35729/changed -d "{\"files\":[\"style.css\"]}"`');
});

// Example of how to trigger a reload programmatically
// setTimeout(() => {
//   lrserver.changed({ body: { files: ['index.html'] } });
//   console.log('Triggered a reload after 5 seconds.');
// }, 5000);