this article demonstrates how to create a simple live reload mechanism for html content using bun's built-in http server and server-sent events (sse). this allows the browser to automatically refresh whenever the server-side code changes, eliminating the need for manual refreshes.

The Problem: Bun's bun -hot command reloads the server on code changes, but the browser doesn't automatically refresh, requiring manual intervention.

The Solution (SSE): This approach leverages SSE, a unidirectional communication method (server to browser), avoiding the overhead of a full WebSocket connection. When the server restarts (due to code changes), it sends an SSE message to the browser, triggering a page reload.

Implementation Steps:

1. SSE Endpoint: Create a /__bun_live_reload endpoint that returns a ReadableStream with a text/event-stream content type. This stream will send the reload signal.

2. Injecting the Client-Side Script: A JavaScript snippet is injected into every HTML response. This script uses the EventSource API to listen for messages from the /__bun_live_reload endpoint. Upon receiving a message, location.reload() refreshes the page.

3. Handling Server Reloads: Bun's hot reload mechanism is utilized. A global variable (globalThis.client) stores the ReadableStreamDefaultController. When the server restarts, a message ("data: ") is sent via globalThis.client?.enqueue() to the browser through the SSE stream.

4. withHtmlLiveReload Wrapper: A function wraps the original fetch handler. It intercepts responses, injects the client-side script, and handles the SSE endpoint.

Code (bun-html-live-reload.ts):

declare global {
  var client: ReadableStreamDefaultController | undefined;
}

type Fetch = (req: Request) => Promise<Response>;

const liveReloadScript = `
  new EventSource("/__bun_live_reload").onmessage = () => {
    location.reload();
  };
`;

export function withHtmlLiveReload(handler: Fetch): Fetch {
  return async (req) => {
    if (new URL(req.url).pathname === "/__bun_live_reload") {
      const stream = new ReadableStream({
        start(controller) {
          globalThis.client = controller;
        },
      });
      return new Response(stream, {
        headers: {
          "Content-Type": "text/event-stream",
          "Cache-Control": "no-cache",
        },
      });
    }

    const response = await handler(req);
    const htmlText = await response.text();
    const newHtmlText = htmlText + liveReloadScript;
    return new Response(newHtmlText, { headers: response.headers });
  };
}

// Example usage in your server.ts:
import { withHtmlLiveReload } from "./bun-html-live-reload";

bun.serve({
  fetch: withHtmlLiveReload(async (req) => {
    return new Response("<h1>Hello, world!</h1>", {
      headers: { "Content-Type": "text/html" },
    });
  }),
});

// In your server.ts, make sure to add this to trigger the reload:
globalThis.client?.enqueue("data:

");

By using this withHtmlLiveReload function, you can easily add live reload functionality to your Bun server-rendered websites. Remember to run your server with bun -hot.