Simple Hot Reload Server

Common errors

• Error: listen EADDRINUSE :::8082

  cause The default port 8082 is already in use by another application or process on your system.
  fix Specify an alternative port using the `-p` or `--port` command-line option, for example: `npx simple-hot-reload-server -p 8083 public`.

• hrs: command not found

  cause The `hrs` command-line tool is not globally installed or `npx` cannot locate it.
  fix If not using `npx`, install it globally: `npm install -g simple-hot-reload-server`. Alternatively, ensure you are running it via `npx` from your project root: `npx simple-hot-reload-server [path]`.

• Files are not hot reloading despite changes being saved.

  cause The `hotRule` configuration might not match the file types you are editing, or the files are not `html`/`htm` or directly referenced by them.
  fix Verify that your `hrs.config.js` includes a `hotRule` that matches the file extensions you expect to hot reload. For instance, `hotRule: /\.(html|htm|css|js)$/` would enable hot reloading for CSS and JS files.

Warnings

• gotcha The package's primary mechanism for hot reloading is explicitly limited to files ending with `.html`, `.htm`, or files that are required by these HTML/HTM files. Other file types might not trigger a hot reload unless specifically configured via `hotRule` in `hrs.config.js` or if they are indirectly included by HTML.
  Fix: For non-HTML/HTM files to trigger hot reloads, configure the `hotRule` option in your `hrs.config.js` to match the desired file extensions (e.g., `/\.(html|htm|css|js)$/`).
• gotcha The project appears to be in maintenance mode, with its last commit observed in late 2021. This could lead to compatibility issues with newer Node.js versions, updated browser standards, or modern JavaScript syntax/features if not actively kept up-to-date by the community or direct contributions.
  Fix: Thoroughly test with your target Node.js version and browser environments. Consider alternative, more actively maintained live/hot-reloading development servers (e.g., `live-server`, `browser-sync`) if encountering modern compatibility challenges.
• gotcha The `hrs.config.js` file, which is crucial for advanced configurations like proxies and custom Express middleware, is designed as a CommonJS module (`module.exports`). Attempting to use ESM `import`/`export` syntax directly in this configuration file will result in errors.
  Fix: Ensure `hrs.config.js` uses CommonJS syntax (`module.exports = { ... }`). If you need to include ESM-only modules, you might need to use dynamic `import()` within the CommonJS context if your Node.js version supports it.

Install

• npm install simple-hot-reload-server npm
• yarn add simple-hot-reload-server yarn
• pnpm add simple-hot-reload-server pnpm

Imports

• start
  wrong:

  import { start } from 'simple-hot-reload-server';

  correct:

  const { start } = require('simple-hot-reload-server');

  The package primarily uses CommonJS `module.exports`, so `require()` is the idiomatic way. While Node.js might handle ESM `import` for named exports, `require()` ensures compatibility given the package's architecture.
• HotReloadServer
  wrong:

  import HotReloadServer from 'simple-hot-reload-server';

  correct:

  const { HotReloadServer } = require('simple-hot-reload-server');

  Accesses the `HotReloadServer` class for programmatic instantiation. Follows the CommonJS `require()` pattern, as it's a named export from the main module.
• CLI Usage
  wrong:

  import hrs from 'simple-hot-reload-server';

  correct:

  npx hrs [path] --port 8082

  The primary intended usage is as a command-line tool via `hrs` (after global installation or `npx`). Direct import of `hrs` as a default export is not supported, and its core functionality is exposed through the CLI or named exports like `start`.

Quickstart

Demonstrates setting up a `simple-hot-reload-server` with a basic `hrs.config.js` for custom routes and proxying, alongside simple HTML, CSS, and JS files for hot reloading.

/* hrs.config.js */
module.exports = {
  // Default port is 8082, can be overridden by CLI -p option
  port: 8082,
  // Watch for changes in .html, .htm files by default
  // hotRule: /\.(html|htm)$/, 
  proxy: {
    '/api': {
      target: 'http://localhost:3000', // Example backend API
      changeHost: true
    }
  },
  setUp: function (app) {
    // app is an Express server object
    app.get('/hello', (req, res) => {
      res.send('Hello from custom Express route!');
    });
  }
};

/* public/index.html */
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Simple Hot Reload</title>
  <link rel="stylesheet" href="./style.css">
</head>
<body>
  <h1>Welcome!</h1>
  <p>This content will hot reload.</p>
  <button onclick="alert('Hello from inline JS!');">Click Me</button>
  <script src="./script.js"></script>
</body>
</html>

/* public/style.css */
body {
  font-family: sans-serif;
  background-color: #f0f0f0;
  color: #333;
}
h1 {
  color: #007bff;
}

/* public/script.js */
console.log('Script loaded. Changes here will also hot reload.');
document.addEventListener('DOMContentLoaded', () => {
  const p = document.querySelector('p');
  if (p) {
    p.textContent = 'Content updated by JavaScript and will hot reload!';
  }
});

// To run:
// 1. Save the above files in your project directory:
//    - hrs.config.js in the root
//    - index.html, style.css, script.js inside a 'public' folder
// 2. Open your terminal in the project root and run:
//    npx simple-hot-reload-server public
// 3. Open http://localhost:8082 in your browser.
//    Modify index.html, style.css, or script.js and save to see hot reload.