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";
import { Hono } from "npm:hono";

const app = new Hono();
// Your routes and middleware here...

// Wrap your app.fetch with liveReload
export default liveReload(app.fetch, import.meta.url);

Option 2: Manual script injection

Add this script tag to your HTML:

<script type="module" src="https://esm.town/v/stevekrouse/live-reload/client.ts"></script>

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.

Limitations

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

How to Contribute

Fork the project
Make your changes
Submit a pull request

Credits

This project was inspired by reloadOnSave by Steve Krouse.