@lopatnov/express-reverse-proxy 2.0.0 → 4.0.0

package/README.md

@@ -20,11 +20,19 @@
 - [CLI Options](#cli-options)
 - [Configuration](#configuration)
   - [port](#port)
+  - [logging](#logging)
+  - [hotReload](#hotreload)
+  - [compression](#compression)
+  - [helmet](#helmet)
+  - [cors](#cors)
+  - [favicon](#favicon)
+  - [responseTime](#responsetime)
   - [headers](#headers)
   - [folders](#folders)
   - [proxy](#proxy)
   - [unhandled](#unhandled)
   - [host](#host)
+  - [ssl](#ssl)
 - [Configuration Recipes](#configuration-recipes)
 - [Docker & PM2](#docker--pm2)
 - [Testing](#testing)
@@ -154,6 +162,15 @@ Static files always take priority over proxy rules. Proxies are checked only whe
 
 ## CLI Options
 
+The package installs two equivalent commands — use whichever you prefer:
+
+```shell
+express-reverse-proxy [options]
+lerp [options]
+```
+
+`lerp` is a short alias for **L**opatnov **E**xpress **R**everse **P**roxy.
+
 | Option                    | Description                                                                                     |
 | ------------------------- | ----------------------------------------------------------------------------------------------- |
 | `--help`                  | Print help and exit                                                                             |
@@ -218,6 +235,55 @@ The port the server listens on. Defaults to `8000`. Can also be set via the `POR
 }
 ```
 
+### logging
+
+Controls HTTP request logging (Morgan). Enabled by default. Set to `false` to silence per-request log lines — useful in production behind another proxy, or to keep console output clean.
+
+```json
+{
+  "port": 8080,
+  "logging": false,
+  "folders": "www"
+}
+```
+
+### hotReload
+
+Watches the `folders` directories for file changes and automatically reloads connected browser tabs. Uses Server-Sent Events (SSE). Intended for local development only.
+
+```json
+{
+  "port": 8080,
+  "hotReload": true,
+  "folders": "www"
+}
+```
+
+The server exposes two endpoints when hot reload is enabled:
+
+| Endpoint | Description |
+| --------------------------------- | ------------------------------------------ |
+| `GET /__hot-reload__` | SSE stream — browsers subscribe here |
+| `GET /__hot-reload__/client.js` | Ready-to-use client script |
+
+#### Connecting the client
+
+**Option A — plain HTML project**: add a script tag to your page. The file is served directly by the dev server, no installation needed:
+
+```html
+<script src="/__hot-reload__/client.js"></script>
+```
+
+**Option B — bundled project** (Vite, webpack, etc.): import the client module. The bundler resolves it through the package `exports` field:
+
+```js
+import '@lopatnov/express-reverse-proxy/hot-reload-client';
+```
+
+Both options connect to `/__hot-reload__` and call `location.reload()` when a file change is detected. The connection is re-established automatically after 3 seconds if the server restarts.
+
+> **PM2 note:** hot reload works best with a single process (`node server.js`). If using PM2, set `instances: 1` in your ecosystem config — each worker maintains its own file watcher and SSE client list independently.
+
 ### headers
 
 Add headers to every response — useful for CORS in development.
@@ -385,6 +451,136 @@ To use multi-site mode, make the config file an **array** instead of an object.
 >
 > Two entries with the same `host` **and** `port` cause a startup error. The same `host` on different ports is allowed.
 
+### ssl
+
+Enable HTTPS on a port by adding an `ssl` object to any site config for that port. All sites sharing the same port use the same certificate.
+
+| Field  | Type     | Description                                              |
+| ------ | -------- | -------------------------------------------------------- |
+| `key`  | `string` | Path to the private key file (PEM format)                |
+| `cert` | `string` | Path to the certificate file (PEM format)                |
+| `ca`   | `string` | *(optional)* Path to the CA bundle for client validation |
+
+Paths are resolved **relative to the config file**, not the current working directory.
+
+```json
+{
+  "port": 443,
+  "ssl": {
+    "key": "./certs/key.pem",
+    "cert": "./certs/cert.pem"
+  },
+  "folders": "./public",
+  "proxy": {
+    "/api": "http://localhost:4000"
+  }
+}
+```
+
+> All site configs on the same port must either all have `ssl` or none — mixing is a startup error.
+
+### compression
+
+Enable gzip/deflate response compression. Reduces the size of HTML, CSS, JS, and JSON responses sent to the browser. Set to `true` for defaults, or pass an options object.
+
+```json
+{
+  "port": 8080,
+  "compression": true,
+  "folders": "www"
+}
+```
+
+With custom options (see [compression docs](https://github.com/expressjs/compression#options)):
+
+```json
+{
+  "compression": { "level": 6, "threshold": 1024 }
+}
+```
+
+> Compression is applied per-site. Assets that are already compressed (images, fonts, video) are not affected — the browser signals it accepts compressed responses via the `Accept-Encoding` header.
+
+### helmet
+
+Set security-related HTTP response headers. Protects against common web vulnerabilities by configuring headers such as `Content-Security-Policy`, `X-Frame-Options`, `Strict-Transport-Security`, and others.
+
+```json
+{
+  "port": 8080,
+  "helmet": true,
+  "folders": "www"
+}
+```
+
+Disable a specific header (see [helmet docs](https://helmetjs.github.io/) for all options):
+
+```json
+{
+  "helmet": { "contentSecurityPolicy": false }
+}
+```
+
+> When `helmet: true` is set, the default helmet configuration is applied. This may block inline scripts and cross-origin resources. Adjust `contentSecurityPolicy` or other options as needed for your project.
+
+### cors
+
+Enable CORS (Cross-Origin Resource Sharing) headers and handle preflight `OPTIONS` requests automatically. Useful when your front-end on one origin calls an API on a different origin.
+
+```json
+{
+  "port": 8080,
+  "cors": true,
+  "proxy": { "/api": "http://localhost:4000" }
+}
+```
+
+Restrict to a specific origin (see [cors docs](https://github.com/expressjs/cors#configuration-options)):
+
+```json
+{
+  "cors": { "origin": "https://app.example.com" }
+}
+```
+
+> The `cors` middleware handles `OPTIONS` preflight requests that the `headers` option cannot respond to. Use `cors` when you need to allow requests from JavaScript on a different domain — for example a React app calling this proxy's API routes.
+
+### favicon
+
+Serve a favicon file efficiently. The file is read into memory at startup and served from there on every `/favicon.ico` request — before static folder scanning or proxy rules run.
+
+```json
+{
+  "port": 8080,
+  "favicon": "./public/favicon.ico",
+  "folders": "www"
+}
+```
+
+The path is resolved **relative to the config file**, consistent with the `ssl` option. Absolute paths are also accepted.
+
+> If your favicon already lives inside a directory listed in `folders`, this option is not needed — `express.static` will serve it automatically.
+
+### responseTime
+
+Add an `X-Response-Time` header to every response, recording how long the server took to handle the request. Useful for performance monitoring and debugging.
+
+```json
+{
+  "port": 8080,
+  "responseTime": true,
+  "folders": "www"
+}
+```
+
+With custom precision (see [response-time docs](https://github.com/expressjs/response-time#options)):
+
+```json
+{
+  "responseTime": { "digits": 0, "suffix": false }
+}
+```
+
 ---
 
 ## Configuration Recipes
@@ -422,6 +618,57 @@ Only `/api/*` requests go to the back-end; everything else stays local.
 - `GET /api/users` → proxied to `http://localhost:4000/users`
 - `GET /missing` → 404 Not Found
 
+### HTTPS with a self-signed certificate (local dev)
+
+```shell
+mkdir certs
+openssl req -x509 -newkey rsa:2048 -keyout certs/key.pem -out certs/cert.pem \
+  -days 365 -nodes -subj "/CN=localhost"
+```
+
+```json
+{
+  "port": 8443,
+  "ssl": {
+    "key": "./certs/key.pem",
+    "cert": "./certs/cert.pem"
+  },
+  "folders": "www",
+  "proxy": {
+    "/api": "http://localhost:4000"
+  }
+}
+```
+
+Start and open in browser (accept the self-signed cert warning):
+
+```shell
+node server.js --config server-config.json
+# [listen] https://localhost:8443
+```
+
+---
+
+### Production hardening (helmet + cors + compression)
+
+Enable security headers, CORS, and response compression in one config:
+
+```json
+{
+  "port": 8080,
+  "compression": true,
+  "helmet": true,
+  "cors": { "origin": "https://app.example.com" },
+  "responseTime": true,
+  "folders": "www",
+  "proxy": {
+    "/api": "http://localhost:4000"
+  }
+}
+```
+
+---
+
 ### CORS headers + rich error responses
 
 ```json
@@ -519,6 +766,56 @@ express-reverse-proxy --cluster status
 express-reverse-proxy --cluster stop
 ```
 
+### Behind a reverse proxy
+
+For production deployments it is common to place a dedicated reverse proxy in front of `express-reverse-proxy` to handle TLS termination, HTTP/2, gzip compression, and rate limiting. In this setup the Node.js server listens on a local port over plain HTTP, while the outer proxy terminates HTTPS connections from the internet:
+
+```
+Internet (HTTPS / HTTP/2)
+        ↓
+  Nginx or Caddy          — TLS, HTTP/2, gzip, rate limiting
+        ↓ HTTP/1.1 (localhost)
+  express-reverse-proxy   — PM2 cluster, routing, static files, API proxy
+        ↓
+  Backend API servers
+```
+
+**No `ssl` config needed** in `server-config.json` when the outer proxy handles TLS.
+
+#### Nginx
+
+```nginx
+server {
+    listen 443 ssl;
+    server_name example.com;
+
+    ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
+
+    location / {
+        proxy_pass         http://127.0.0.1:8080;
+        proxy_set_header   Host              $host;
+        proxy_set_header   X-Real-IP         $remote_addr;
+        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
+        proxy_set_header   X-Forwarded-Proto $scheme;
+    }
+}
+```
+
+Free certificates can be obtained with [Certbot](https://certbot.eff.org/): `certbot --nginx -d example.com`.
+
+#### Caddy
+
+[Caddy](https://caddyserver.com/) provisions and renews Let's Encrypt certificates automatically — no extra tooling needed:
+
+```
+example.com {
+    reverse_proxy 127.0.0.1:8080
+}
+```
+
+Start with `caddy run --config Caddyfile`.
+
 ---
 
 ## Testing
@@ -649,6 +946,11 @@ Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) before
 - [Express](https://expressjs.com/) — HTTP server framework
 - [express-http-proxy](https://github.com/villadora/express-http-proxy) — reverse proxy middleware
 - [Morgan](https://github.com/expressjs/morgan) — HTTP request logger
+- [compression](https://github.com/expressjs/compression) — gzip/deflate response compression
+- [helmet](https://helmetjs.github.io/) — security HTTP headers
+- [cors](https://github.com/expressjs/cors) — CORS headers and preflight handling
+- [serve-favicon](https://github.com/expressjs/serve-favicon) — efficient favicon serving
+- [response-time](https://github.com/expressjs/response-time) — X-Response-Time header
 - [PM2](https://pm2.keymetrics.io/) — production process manager with clustering
 - [Biome](https://biomejs.dev/) — fast linter and formatter (Rust-based)
 - [Cypress](https://www.cypress.io/) — E2E testing framework

package/ecosystem.config.cjs

@@ -1,24 +1,24 @@
-const path = require('node:path');
-
-module.exports = {
-  apps: [
-    {
-      name: 'express-reverse-proxy',
-      script: path.join(__dirname, 'server.js'),
-      instances: 'max',
-      exec_mode: 'cluster',
-      wait_ready: true,
-      listen_timeout: 30000,
-      kill_timeout: 5000,
-      shutdown_with_message: true,
-      vizion: false, // disable git metadata collection
-      pmx: false, // disable PM2 metrics (avoids wmic ENOENT on Windows 11)
-      env: {
-        NODE_ENV: 'production',
-      },
-      env_development: {
-        NODE_ENV: 'development',
-      },
-    },
-  ],
-};
+const path = require('node:path');
+
+module.exports = {
+  apps: [
+    {
+      name: 'express-reverse-proxy',
+      script: path.join(__dirname, 'server.js'),
+      instances: 'max',
+      exec_mode: 'cluster',
+      wait_ready: true,
+      listen_timeout: 30000,
+      kill_timeout: 5000,
+      shutdown_with_message: true,
+      vizion: false, // disable git metadata collection
+      pmx: false, // disable PM2 metrics (avoids wmic ENOENT on Windows 11)
+      env: {
+        NODE_ENV: 'production',
+      },
+      env_development: {
+        NODE_ENV: 'development',
+      },
+    },
+  ],
+};

package/hot-reload-client.js

@@ -0,0 +1,31 @@
+/**
+ * Hot Reload Client — connect via SSE and reload the page when files change.
+ *
+ * Usage (choose one):
+ *
+ *   <!-- as a plain script tag -->
+ *   <script src="/__hot-reload__/client.js"></script>
+ *
+ *   <!-- as an ES module (bundler resolves via package.json exports) -->
+ *   import '@lopatnov/express-reverse-proxy/hot-reload-client';
+ *
+ * The server must have `"hotReload": true` in its server-config.json.
+ */
+(function hotReloadClient() {
+  var url = '/__hot-reload__';
+
+  function connect() {
+    var es = new EventSource(url);
+
+    es.onmessage = () => {
+      location.reload();
+    };
+
+    es.onerror = () => {
+      es.close();
+      setTimeout(connect, 3000);
+    };
+  }
+
+  connect();
+})();

package/package.json

@@ -1,16 +1,18 @@
 {
   "name": "@lopatnov/express-reverse-proxy",
   "email": "oleksandr@lopatnov.cv.ua",
-  "version": "2.0.0",
+  "version": "4.0.0",
   "description": "Node.js CLI tool to serve static front-end files with a reverse proxy for back-end APIs",
   "type": "module",
   "author": "lopatnov",
   "main": "server.js",
   "exports": {
-    ".": "./server.js"
+    ".": "./server.js",
+    "./hot-reload-client": "./hot-reload-client.js"
   },
   "bin": {
-    "express-reverse-proxy": "./server.js"
+    "express-reverse-proxy": "./server.js",
+    "lerp": "./server.js"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -57,6 +59,7 @@
   "homepage": "https://lopatnov.github.io/express-reverse-proxy/",
   "files": [
     "server.js",
+    "hot-reload-client.js",
     "ecosystem.config.cjs",
     "README.md",
     "LICENSE"
@@ -65,10 +68,15 @@
     "access": "public"
   },
   "dependencies": {
+    "compression": "^1.7.5",
+    "cors": "^2.8.5",
     "express": "^5.2.1",
     "express-http-proxy": "^2.1.2",
+    "helmet": "^8.0.0",
     "morgan": "^1.10.1",
-    "pm2": "^6.0.14"
+    "pm2": "^6.0.14",
+    "response-time": "^2.3.2",
+    "serve-favicon": "^2.5.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.2",

package/server.js

@@ -1,11 +1,17 @@
 #!/usr/bin/env node
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
+import https from 'node:https';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import compression from 'compression';
+import cors from 'cors';
 import express from 'express';
 import proxy from 'express-http-proxy';
+import helmet from 'helmet';
 import morgan from 'morgan';
+import responseTime from 'response-time';
+import favicon from 'serve-favicon';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -151,6 +157,7 @@ if (serverArgs['--config']) {
     configFile = path.join(configFile, './server-config.json');
   }
 }
+const configDir = path.dirname(path.resolve(configFile));
 
 const DEFAULT_CONFIG = { port: 8000, folders: '.' };
 
@@ -194,6 +201,21 @@ configs.forEach((c) => {
   configsByPort.get(p).push(c);
 });
 
+// Validate: cannot mix SSL and non-SSL site configs on the same port
+for (const [p, group] of configsByPort) {
+  const sslCount = group.filter((c) => c.ssl).length;
+  if (sslCount > 0 && sslCount < group.length) {
+    exitError(`Port ${p}: cannot mix SSL and non-SSL site configs on the same port.`, 1);
+  }
+}
+
+function collectFolderPaths(folders) {
+  if (typeof folders === 'string') return [folders];
+  if (Array.isArray(folders)) return folders.flatMap(collectFolderPaths);
+  if (folders instanceof Object) return Object.values(folders).flatMap(collectFolderPaths);
+  return [];
+}
+
 function addStaticFolderByName(router, port, urlPath, folder) {
   let folderPath = folder;
   if (!path.isAbsolute(folder)) {
@@ -290,7 +312,47 @@ const servers = [];
 
 configsByPort.forEach((portConfigs, p) => {
   const app = express();
-  app.use(morgan('combined'));
+  const loggingEnabled = portConfigs.every((c) => c.logging !== false);
+  if (loggingEnabled) {
+    app.use(morgan('combined'));
+  }
+
+  // Hot reload via SSE
+  const hotReloadEnabled = portConfigs.some((c) => c.hotReload === true);
+  if (hotReloadEnabled) {
+    const sseClients = new Set();
+    let reloadTimer = null;
+
+    app.get('/__hot-reload__', (req, res) => {
+      res.setHeader('Content-Type', 'text/event-stream');
+      res.setHeader('Cache-Control', 'no-cache');
+      res.setHeader('Connection', 'keep-alive');
+      res.flushHeaders();
+      sseClients.add(res);
+      req.on('close', () => sseClients.delete(res));
+    });
+
+    app.get('/__hot-reload__/client.js', (_req, res) => {
+      res.setHeader('Content-Type', 'application/javascript; charset=utf-8');
+      res.sendFile(path.join(__dirname, 'hot-reload-client.js'));
+    });
+
+    const watchPaths = [
+      ...new Set(portConfigs.flatMap((c) => collectFolderPaths(c.folders || []))),
+    ];
+    for (const folder of watchPaths) {
+      const absPath = path.isAbsolute(folder) ? folder : path.join(process.cwd(), folder);
+      if (fs.existsSync(absPath)) {
+        fs.watch(absPath, { recursive: true }, () => {
+          clearTimeout(reloadTimer);
+          reloadTimer = setTimeout(() => {
+            for (const client of sseClients) client.write('data: reload\n\n');
+          }, 100);
+        });
+      }
+    }
+    console.log(`[hot-reload] watching ${watchPaths.length} folder(s) on port ${p}`);
+  }
 
   // Specific hosts first, catch-all last
   const sorted = [
@@ -304,6 +366,30 @@ configsByPort.forEach((portConfigs, p) => {
 
     console.log(`[host] ${siteHost} → :${p}`);
 
+    if (siteConfig.responseTime) {
+      const opts = typeof siteConfig.responseTime === 'object' ? siteConfig.responseTime : {};
+      router.use(responseTime(opts));
+    }
+
+    if (siteConfig.cors) {
+      const opts = typeof siteConfig.cors === 'object' ? siteConfig.cors : {};
+      router.use(cors(opts));
+    }
+
+    if (siteConfig.compression) {
+      const opts = typeof siteConfig.compression === 'object' ? siteConfig.compression : {};
+      router.use(compression(opts));
+    }
+
+    if (siteConfig.helmet) {
+      const opts = typeof siteConfig.helmet === 'object' ? siteConfig.helmet : {};
+      router.use(helmet(opts));
+    }
+
+    if (siteConfig.favicon) {
+      router.use(favicon(path.resolve(configDir, siteConfig.favicon)));
+    }
+
     if (siteConfig.headers) {
       router.use((_req, res, next) => {
         for (const h of Object.keys(siteConfig.headers)) res.setHeader(h, siteConfig.headers[h]);
@@ -341,10 +427,31 @@ configsByPort.forEach((portConfigs, p) => {
     }
   });
 
-  const server = app.listen(p, () => {
-    console.log(`[listen] http://localhost:${p}`);
-    if (process.send) process.send('ready');
-  });
+  const sslConfig = portConfigs.find((c) => c.ssl)?.ssl;
+  let server;
+  if (sslConfig) {
+    let sslOptions;
+    try {
+      sslOptions = {
+        key: fs.readFileSync(path.resolve(configDir, sslConfig.key)),
+        cert: fs.readFileSync(path.resolve(configDir, sslConfig.cert)),
+      };
+      if (sslConfig.ca) {
+        sslOptions.ca = fs.readFileSync(path.resolve(configDir, sslConfig.ca));
+      }
+    } catch (err) {
+      exitError(`SSL cert/key error on port ${p}: ${err.message}`, 1);
+    }
+    server = https.createServer(sslOptions, app).listen(p, () => {
+      console.log(`[listen] https://localhost:${p}`);
+      if (process.send) process.send('ready');
+    });
+  } else {
+    server = app.listen(p, () => {
+      console.log(`[listen] http://localhost:${p}`);
+      if (process.send) process.send('ready');
+    });
+  }
   server.on('error', (err) => {
     if (err.code === 'EADDRINUSE') {
       exitError(`Port ${p} is already in use`, 1);