Live reload support (--live flag)

[melvincarvalho]

Summary

Add live reload functionality similar to Vite's dev server, leveraging JSS's existing WebSocket notifications system.

Motivation

When using servejss for local development, it would be convenient to have the browser automatically refresh when files change. This is a standard feature in modern dev servers like Vite, webpack-dev-server, and browser-sync.

Since JSS already has WebSocket notifications that emit change events on PUT/DELETE, we're 80% of the way there.

Proposed Solution

Phase 1: Basic Live Reload (~30 LOC)

Add a --live flag that:

1. Injects a client script into HTML responses

   // Injected before </body>
   <script>
   (function() {
     const ws = new WebSocket(`ws://${location.host}/notifications/`);
     ws.onmessage = function(e) {
       const data = JSON.parse(e.data);
       if (data.type === 'update') {
         console.log('[servejss] File changed, reloading...');
         location.reload();
       }
     };
     ws.onclose = function() {
       console.log('[servejss] Connection lost, reconnecting...');
       setTimeout(() => location.reload(), 1000);
     };
   })();
   </script>

2. Enable notifications automatically when --live is used

Phase 2: Smart Reload (Optional)

• CSS hot swap: Update <link> href with cache-busting query instead of full reload
• Filtered reloads: Only reload when the current page or its dependencies change
• Debouncing: Batch rapid changes into single reload

Phase 3: HMR (Future/Optional)

True Hot Module Replacement would require:

• Module dependency graph tracking
• Framework-specific plugins (React, Vue, Svelte)
• Significantly more complexity

This is out of scope for initial implementation.

Usage

# Serve with live reload
servejss --live

# Combine with other options
servejss --live -p 8080 ./src

Output

 servejss 

  Directory:  /home/user/project

  Local:      http://localhost:3000
  Network:    http://192.168.1.5:3000

  Mode:       GET/PUT/DELETE enabled
  Live:       Watching for changes ✓

  Press Ctrl+C to stop

Implementation Notes

• Requires enabling --notifications in JSS under the hood
• HTML injection should only apply to text/html responses
• Script injection point: before </body> or end of document
• Consider adding visual indicator (toast/overlay) on reload

Alternatives Considered

1. External tool: Use browser-sync or livereload separately

   • Pro: No changes needed
   • Con: Extra dependency, more complex setup

2. Server-sent events: Instead of WebSocket

   • Pro: Simpler protocol
   • Con: JSS already uses WebSocket, would duplicate effort

Difficulty Estimate

• Phase 1 (Basic): ~30/100 - Few hours of work
• Phase 2 (Smart): ~50/100 - Day or two
• Phase 3 (HMR): ~80/100 - Significant effort, probably not worth it

Related

• JSS WebSocket notifications: src/notifications/websocket.js
• Vite HMR: https://vite.dev/guide/api-hmr.html
• livereload protocol: http://livereload.com/