Tiny LiveReload Server

Common errors

• Error: listen EADDRINUSE :::35729

  cause Another process is already using port 35729, which is the default for LiveReload. This often happens if a previous instance of tiny-lr or another application using this port was not properly shut down.
  fix Ensure no other applications are running on port 35729. On Linux/macOS, use `lsof -i :35729` to identify and kill the process. On Windows, use `netstat -ano | findstr :35729` and then `taskkill /PID <PID> /F`.

• TypeError: app.use is not a function

  cause This error occurs if `tinylr.middleware` is called without providing an Express/Connect application instance, or if `app` is not a valid Express/Connect app.
  fix When using `tinylr.middleware`, ensure you pass a valid Express/Connect application instance, e.g., `tinylr.middleware({ app: app })` where `app = express();`.

• Error: Not Found (404) for /changed endpoint

  cause This usually indicates that the `tiny-lr` server or its middleware is not correctly configured or running, or `body-parser` is missing for POST requests.
  fix Verify that `lrServer.listen()` is called and the server is running, or that `app.use(tinylr.middleware({ app: app }))` is in your Express app's middleware stack, preceded by `body-parser` if using POST requests. Check the port being targeted.

• Browser LiveReload extension not working/connecting

  cause The most common causes are the tiny-lr server not running on the standard port 35729, the browser extension not being enabled, or a firewall blocking the connection.
  fix Confirm tiny-lr is listening on port 35729. Check your browser's extension icon to ensure LiveReload is active for your page. Inspect browser console for `livereload.js` connection errors. Disable firewalls temporarily for testing.

Warnings

• breaking Version 2.0.0 of tiny-lr includes a breaking change where the underlying `livereload-js` client library dropped support for Internet Explorer versions 6-9. Projects requiring compatibility with these legacy browsers should use an older version of tiny-lr or find an alternative.
  Fix: Upgrade browser target to modern browsers (IE10+ or equivalent) or downgrade tiny-lr to a 1.x version if IE 6-9 support is critical, understanding that older versions may have known vulnerabilities.
• gotcha For browser extensions (e.g., Chrome, Firefox LiveReload extensions) to function correctly, tiny-lr *must* listen on its standard port `35729`. If a different port is used, users must manually inject the LiveReload client-side script into their HTML.
  Fix: Always configure the tiny-lr server to listen on port `35729` (e.g., `lrServer.listen(35729)`).
• gotcha tiny-lr is a notification server only; it does not include file watching capabilities. Developers must integrate it with a separate file watcher (e.g., Gulp, Grunt, Webpack, chokidar) that detects changes and then sends notifications to tiny-lr's API.
  Fix: Ensure your build system or development workflow includes a file watcher that explicitly calls tiny-lr's `/changed` endpoint (via HTTP POST/GET or `lrServer.changed()`) when files are modified.
• gotcha When using tiny-lr as Express/Connect middleware for handling POST requests (e.g., `POST /changed`), `body-parser` (or similar middleware) is required to be mounted *before* tiny-lr's middleware in the application stack to parse the request body.
  Fix: Add `app.use(bodyParser.json());` and/or `app.use(bodyParser.urlencoded({ extended: true }));` before `app.use(tinylr.middleware({ app: app }));`.
• deprecated The package was largely unmaintained for an extended period prior to version 2.0.0, leading to forks like `mini-lr` and `tiny-lr-fork` to address issues, particularly with npm v3's flat module directory structure. While tiny-lr is now active, be aware of its historical maintenance gaps.
  Fix: Always use the latest stable version (2.0.0 or higher) of `tiny-lr` to benefit from recent dependency updates and bug fixes. Avoid using abandoned forks.

Install

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

Imports

• tinylr
  wrong:

  import tinylr from 'tiny-lr';

  correct:

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

  tiny-lr primarily uses CommonJS `require` syntax. As of v2.0.0, there is no official ESM support. The default export is a factory function that returns a server instance.
• tinylr.Server
  wrong:

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

  correct:

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

  The `Server` class can be accessed directly for more explicit instantiation, though the default `tinylr()` factory is more common. Still CommonJS only.
• tinylr.middleware
  wrong:

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

  correct:

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

  The Express/Connect middleware is a named export available on the main `tiny-lr` module. It requires `body-parser` to be used earlier in the middleware stack for handling POST requests.

Quickstart

This quickstart demonstrates setting up a tiny-lr server on its standard port and integrating its middleware with an Express application. It also shows how to programmatically trigger a file change notification to connected LiveReload clients.

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

const port = process.env.LR_PORT || 35729; // Standard LiveReload port
const app = express();

// Start the LiveReload server independently
const lrServer = tinylr();
lrServer.listen(port, function() {
  console.log(`LiveReload server listening on port ${port} (for browser extensions).`);
});

// Or integrate as Express middleware
app.use(bodyParser.json());
app.use(bodyParser.urlencoded({ extended: true }));
app.use(tinylr.middleware({ app: app }));

app.use(express.static(path.resolve('./public'))); // Serve static files

app.get('/', (req, res) => {
  res.send('<h1>Hello from tiny-lr!</h1><p>Check the browser console or network tab for livereload.js.</p>');
});

// Example of triggering a reload via HTTP API
// This would typically be called by a build tool when files change.
// curl http://localhost:35729/changed?files=index.html,style.css
// curl -X POST http://localhost:35729/changed -d '{ "files": ["script.js"] }'

app.listen(8000, () => {
  console.log('Express server listening on port 8000.');
  console.log('Open http://localhost:8000 in your browser and ensure LiveReload extension is active or script tag is added.');
  console.log('To trigger a reload, send a POST request to http://localhost:35729/changed with a JSON body: { "files": ["index.html"] }');
});

// To manually trigger a reload (e.g., from your file watcher)
function notifyChange(files) {
  lrServer.changed({ body: { files: files } });
  console.log('Notified LiveReload clients about:', files);
}

// Simulate a file change after 5 seconds
setTimeout(() => {
  notifyChange(['index.html', 'style.css']);
}, 5000);