starlette-hot-reload 0.1.0

Hot reload for Starlette app with smart asset updates and HTML injection

Starlette Hot Reload

starlette-hot-reload is a lightweight hot reload utility for Starlette that provides fast in-browser reloads for templates and static files.

It integrates directly with your Starlette app and provides:

• Automatic HTML injection via middleware.
• Server-Sent Events (SSE) based live reload (no WebSocket dependencies).
• Smart updates, CSS changes reload without a full page refresh.
• Automatic reconnection with exponential backoff.
• Fully typed, following Starlette patterns.
• Zero additional dependencies beyond Starlette.

Installation

uv add starlette-hot-reload
# or
pip install starlette-hot-reload

Example

from starlette.applications import Starlette
from starlette.routing import Route

from starlette_hot_reload import HotReload

routes = [
    # your routes
]

app = Starlette(
    debug=True,
    routes=routes,
)

# Set up hot reload (only active when debug=True)
hot_reload = HotReload(watch_dirs=["templates", "static"])
hot_reload.setup(app)

Run the application using uvicorn:

$ uvicorn main:app

How it works

starlette-hot-reload updates the browser without restarting the server.

It integrates into your app using middleware and a Server-Sent Events (SSE) endpoint.

• HTML responses are automatically modified to include a small client script.
• The client connects to an SSE stream exposed by the app.
• File changes trigger reload events:
  • CSS changes update stylesheets in-place.
  • Other changes trigger a full page reload.
• The client automatically reconnects if the connection is lost.

It complements:

• ASGI server reload (uvicorn --reload)
• Frontend build tools (Vite, Webpack, etc.)

Usage

Hot reload is only active when debug=True.

app = Starlette(debug=True)

You can control which directories are watched:

HotReload(watch_dirs=["templates", "static", "assets"])

You can customize the SSE endpoint path (default is /__starlette_hot_reload):

hot_reload = HotReload(
    watch_dirs=["templates", "static"],
    events_path="/custom-events-path",
)

You can also tune how often the watcher scans for changes. Lower values make reloads feel faster, at the cost of a bit more filesystem polling:

hot_reload = HotReload(
    watch_dirs=["templates", "static"],
    poll_interval=0.25,
)

Debug Logging

To enable debug logging, configure Python's logging module:

import logging
import sys

logging.basicConfig(
    level=logging.DEBUG,
    # ...
)

License

MIT