HotSrv

A high-performance Rust CLI web server with intelligent live reloading for local development.

Features

🚀 Fast & Lightweight - Built with Axum and optimized for performance

🔥 Smart Hot Reload - CSS updates without page refresh, full reload for other files

🧹 Service Worker Aware - Automatically detects and clears service workers when switching projects

🌐 Auto Browser Opening - Opens your default browser automatically (can be disabled)

📁 Directory Listings - Beautiful directory browsing with file/folder icons

⚡ File Streaming - Efficient streaming for large files to minimize memory usage

🎯 Cache Busting - Intelligent cache management prevents stale content

Quick Start

# Serve current directory on default port (3000)
hotsrv

# Serve on custom port with hot reload for CSS
hotsrv --port 8080 --hot-reload

# Serve without opening browser
hotsrv --no-open

# Enable verbose logging
hotsrv --verbose

Installation

From Codeberg

cargo install --git https://codeberg.org/Pontoporeia/hotsrv

Pre-built Binaries

Download from the releases page.

Usage

Usage: hotsrv [OPTIONS]

Options:
  -d, --dir <DIR>      Directory to serve files from [default: .]
  -p, --port <PORT>    Port to serve on [default: 3000]
      --host <HOST>    Host to bind to [default: 127.0.0.1]
  -v, --verbose        Enable verbose logging
      --no-inject      Disable live reload injection
      --hot-reload     Enable hot reload (updates content without full page reload)
      --no-cache-bust  Disable cache busting during reload
      --allow-sw       Allow service worker registration
      --no-open        Don't open browser automatically
  -h, --help           Print help
  -V, --version        Print version

Live Reload Modes

Full Reload (Default)

• Clears all caches and service workers via the Clear-Site-Data header
• Adds cache-busting parameters
• Complete page refresh for all changes

Hot Reload (--hot-reload)

• CSS files update without page refresh
• Other files trigger full page reload
• Preserves application state when possible

Simple Reload (--no-cache-bust)

• Basic page reload without cache clearing
• Fastest reload mode
• May not work with aggressive caching

Service Worker Handling

By default, HotSrv blocks service worker registrations to prevent aggressive caching during development.

• --allow-sw: Use this flag to permit service worker registration if your app requires it.
• Smart Clearing: The injected smart-sw-handler.js detects and unregisters service workers from other projects to prevent cross-project interference.
• Manual Override: Visit /__hotsrv__/clear to manually trigger a Clear-Site-Data header, which wipes caches and storage for the current origin.
• Configuration: The /__hotsrv__/config endpoint provides client-side scripts with the current server configuration (e.g., hot_reload status).

Performance Features

• File Streaming: Large files (>1MB) are streamed to reduce memory usage
• Metadata Caching: File metadata is cached to reduce filesystem calls
• Connection Limiting: SSE connections are limited to prevent resource exhaustion
• Optimized Dependencies: Minimal feature sets and optimized for release builds

Project Structure

hotsrv/
├── src/
│   ├── cli.rs          # Command line interface
│   ├── inject.rs       # JavaScript injection logic
│   ├── main.rs         # Application entry point
│   ├── server.rs       # HTTP server and routing
│   └── js/             # JavaScript modules
│       ├── livereload.js
│       ├── hot-reload.js
│       ├── simple-reload.js
│       └── smart-sw-handler.js
├── assets/             # Logo and static assets
├── CONTRIBUTING.md     # Contribution guidelines
├── BUILDING.md         # Build instructions
└── README.md           # This file

Contributing

See CONTRIBUTING.md for development setup and contribution guidelines.

Building

See BUILDING.md for detailed build instructions and requirements.

License

Licensed under AGPL-3.0-later. See the LICENSE file for details.