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

Option 1: Using the wrapper function (Recommended)

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);

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 your code has errors, the system will continue polling until the errors are fixed

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)

Page keeps refreshing with errors

If your code has errors, the system will keep polling until the errors are fixed. Fix the errors in your code and the page will automatically reload once they're resolved.

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

Credits

This project is a port of reloadOnSave.