feat: add --live-reload flag for auto-refresh on file changes (JavaScriptSolidServer#111)

melvincarvalho · web-flow · commit e80ff35a15db · 2026-01-28T13:49:42.000+01:00
* feat: add --live-reload flag for auto-refresh on file changes Injects a small script into HTML responses that connects to the WebSocket notifications endpoint. When files change, browser reloads. - Auto-enables notifications WebSocket when --live-reload is used - Script injected before </body> in HTML responses - Reconnects automatically if connection drops Usage: jss start --live-reload Closes JavaScriptSolidServer#110 * fix: address Copilot review feedback - Fix WebSocket path: /notifications/ -> /.notifications - Only reload on 'pub' messages (not protocol greeting) - Subscribe to current page URL on connect - Add Cache-Control: no-store when injecting script - Simplify injectLiveReload function (remove unused param) - Inject script for index.html container path too * fix: enable notifications events when live-reload is on * fix: remove ETag header when injecting live reload script
diff --git a/bin/jss.js b/bin/jss.js
@@ -78,6 +78,7 @@ program
   .option('--no-webid-tls', 'Disable WebID-TLS authentication')
   .option('--public', 'Allow unauthenticated access (skip WAC, open read/write)')
   .option('--read-only', 'Disable PUT/DELETE/PATCH methods (read-only mode)')
+  .option('--live-reload', 'Inject live reload script into HTML (auto-refresh on changes)')
   .option('-q, --quiet', 'Suppress log output')
   .option('--print-config', 'Print configuration and exit')
   .action(async (options) => {
@@ -135,6 +136,7 @@ program
         singleUserName: config.singleUserName,
         public: config.public,
         readOnly: config.readOnly,
+        liveReload: config.liveReload,
       });
 
       await server.listen({ port: config.port, host: config.host });
diff --git a/src/config.js b/src/config.js
@@ -79,6 +79,9 @@ export const defaults = {
   // Read-only mode - disable PUT/DELETE/PATCH
   readOnly: false,
 
+  // Live reload - inject script to auto-refresh browser on file changes
+  liveReload: false,
+
   // Logging
   logger: true,
   quiet: false,
@@ -125,6 +128,7 @@ const envMap = {
   JSS_DEFAULT_QUOTA: 'defaultQuota',
   JSS_PUBLIC: 'public',
   JSS_READ_ONLY: 'readOnly',
+  JSS_LIVE_RELOAD: 'liveReload',
 };
 
 /**
diff --git a/src/handlers/resource.js b/src/handlers/resource.js
@@ -17,6 +17,23 @@ import { emitChange } from '../notifications/events.js';
 import { checkIfMatch, checkIfNoneMatchForGet, checkIfNoneMatchForWrite } from '../utils/conditional.js';
 import { generateDatabrowserHtml, generateSolidosUiHtml, shouldServeMashlib } from '../mashlib/index.js';
 
+/**
+ * Live reload script - injected into HTML when --live-reload is enabled
+ */
+const LIVE_RELOAD_SCRIPT = `<script>(function(){var ws=new WebSocket((location.protocol==='https:'?'wss:':'ws:')+'//' +location.host+'/.notifications');ws.onopen=function(){ws.send('sub '+location.href)};ws.onmessage=function(e){if(e.data.startsWith('pub '))location.reload()};ws.onclose=function(){setTimeout(function(){location.reload()},1000)}})();</script>`;
+
+/**
+ * Inject live reload script into HTML content
+ */
+function injectLiveReload(content) {
+  const html = content.toString();
+  // Inject before </body> or at end
+  if (html.includes('</body>')) {
+    return Buffer.from(html.replace('</body>', LIVE_RELOAD_SCRIPT + '</body>'));
+  }
+  return Buffer.from(html + LIVE_RELOAD_SCRIPT);
+}
+
 /**
  * Get the storage path and resource URL for a request
  * In subdomain mode, storage path includes pod name, URL uses subdomain
@@ -198,6 +215,12 @@ export async function handleGet(request, reply) {
       });
 
       Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
+      // Inject live reload script for index.html
+      if (request.liveReloadEnabled) {
+        reply.header('Cache-Control', 'no-store');
+        reply.removeHeader('ETag');
+        return reply.send(injectLiveReload(content));
+      }
       return reply.send(content);
     }
 
@@ -439,6 +462,13 @@ export async function handleGet(request, reply) {
   headers['Vary'] = getVaryHeader(connegEnabled, request.mashlibEnabled);
 
   Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
+
+  // Inject live reload script into HTML (disable caching since content is modified)
+  if (actualContentType === 'text/html' && request.liveReloadEnabled) {
+    reply.header('Cache-Control', 'no-store');
+    reply.removeHeader('ETag');
+    return reply.send(injectLiveReload(content));
+  }
   return reply.send(content);
 }
 
diff --git a/src/server.js b/src/server.js
@@ -79,6 +79,8 @@ export function createServer(options = {}) {
   const defaultQuota = options.defaultQuota ?? 50 * 1024 * 1024;
   // WebID-TLS client certificate authentication is OFF by default
   const webidTlsEnabled = options.webidTls ?? false;
+  // Live reload - injects script to auto-refresh browser on file changes
+  const liveReloadEnabled = options.liveReload ?? false;
 
   // Set data root via environment variable if provided
   if (options.root) {
@@ -136,9 +138,10 @@ export function createServer(options = {}) {
   fastify.decorateRequest('solidosUiEnabled', null);
   fastify.decorateRequest('defaultQuota', null);
   fastify.decorateRequest('config', null);
+  fastify.decorateRequest('liveReloadEnabled', null);
   fastify.addHook('onRequest', async (request) => {
     request.connegEnabled = connegEnabled;
-    request.notificationsEnabled = notificationsEnabled;
+    request.notificationsEnabled = notificationsEnabled || liveReloadEnabled;
     request.idpEnabled = idpEnabled;
     request.subdomainsEnabled = subdomainsEnabled;
     request.baseDomain = baseDomain;
@@ -148,6 +151,7 @@ export function createServer(options = {}) {
     request.solidosUiEnabled = solidosUiEnabled;
     request.defaultQuota = defaultQuota;
     request.config = { public: options.public, readOnly: options.readOnly };
+    request.liveReloadEnabled = liveReloadEnabled;
 
     // Extract pod name from subdomain if enabled
     if (subdomainsEnabled && baseDomain) {
@@ -164,8 +168,8 @@ export function createServer(options = {}) {
     }
   });
 
-  // Register WebSocket notifications plugin if enabled
-  if (notificationsEnabled) {
+  // Register WebSocket notifications plugin if enabled (or live reload needs it)
+  if (notificationsEnabled || liveReloadEnabled) {
     fastify.register(notificationsPlugin);
   }
 
