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 --reload-mode hot

# 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
      --reload-mode <RELOAD_MODE>    How the browser reacts to file changes
                                     [default: full] [possible values: full, hot, simple]
      --no-open                      Don't open browser automatically
      --allow-sw                     Allow service worker registration
  -h, --help                         Print help
  -V, --version                      Print version

Live Reload Modes

Full Reload (Default — --reload-mode full)

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

Hot Reload (--reload-mode hot)

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

Simple Reload (--reload-mode simple)

• 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.

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
│   ├── watcher.rs      # File-system watcher
│   └── js/             # JavaScript modules
│       ├── client.js
│       └── smart-sw-handler.js
├── 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.

AI Disclosure

This tool was developed with the assistance of large language models (LLMs) throughout its history. The following models were used:

• Claude Sonnet 3.5 through Claude Sonnet 4.6 (Anthropic)
• DeepSeek V4 Pro (DeepSeek)

AI assistance was employed for code generation, refactoring, test authoring, documentation, debugging, and project scaffolding. All AI-generated output was reviewed, tested, and validated by a human before inclusion.

License

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