Live-Reload for Val Town

Automatically reload your Val Town project in the browser when any of its files change. No more manual refreshing to see your updates!

Demo video

Features

🔄 Instant page reloads when your code changes
🔌 Simple one-line integration
🧠 Smart polling frequency based on edit recency
🛡️ Error state handling with automatic recovery
🔍 Works only in development environments (*.val.run domains)

Installation

Import and use the liveReload wrapper function in your main entry point:

import { liveReload } from "https://esm.town/v/stevekrouse/live-reload/main.ts";

const handler = (req: Request) => { /* your fetch handler */}
export default liveReload(handler, import.meta.url);

You can also remix this example to get started.

How It Works

Detection: The system uses the Val Town API to monitor your project for changes
Long Polling: The client periodically checks if the project has been updated
Smart Polling: Polling frequency adjusts based on how recently the project was edited:
- < 15 minutes: Polls every 500ms
- < 3 hours: Polls every 1 second
- > 3 hours: Polls every 5 seconds
Reload: When a change is detected, the page is redirected through a special proxy that handles error states
Error Recovery: If val returns an error, we'll redirect you to our reload.val.run proxy, which will show you the error, and poll for non-error responses, and reload the page when it gets one.

Example Usage

Here's a complete example using Hono:

/** @jsxImportSource npm:hono/jsx **/
import { Hono } from "npm:hono";
import { liveReload } from "https://esm.town/v/stevekrouse/live-reload/main.ts";

const app = new Hono();

app.get("/", (c) => {
  return c.html(
    <body>
      <h1>My App with Live Reloading</h1>
      <p>Edit this file and save to see instant updates!</p>
    </body>,
  );
});

// Enable live reloading
export default liveReload(app.fetch, import.meta.url);

Troubleshooting

Live reload isn't working

Check the domain: Live reload only works on *.val.run domains (not custom domains)
Check the console: Look for messages about live-reload being skipped
Iframe detection: Live reload is disabled in iframes (like the Val Town editor preview)

Disabled on development

Only works on *.val.run domains (not custom domains)
Disabled in iframes (including the Val Town editor preview)
Requires the Val Town API to be accessible

Prior Art

This project is a port of reloadOnSave.