webadev 0.9.0

A web dev server with live reload
Documentation

Webadev

A web dev server with live reload, written in Rust.

Features

  • Serve a static folder with HTML, CSS, JS
  • Live reload in the browser on file change, debounced by 200ms
  • CSS hot-reload (no full page reload)
  • Smart script injection (no manual setup needed)
  • Auto-reconnect (reloads the page when the server restarts, requires a --port)
  • Custom IP/port support
  • Serve under a URL path prefix
  • Add headers

If you need to bundle and serve, check Bundla.

CLI

Install and run

cargo install webadev

# serve the current directory
webadev

Options

  • --dir / -d: directory to serve (default: .)
  • --port / -p: port to run on (default: random free port)
  • --ip / -i: IP address to bind to (default: 127.0.0.1, use 0.0.0.0 to access from other devices)
  • --open / -o: open the page in the browser on start (default: false)
  • --header: additional HTTP header on every response (repeatable; e.g. --header "Access-Control-Allow-Origin: *")
  • --index: default file for directory requests (default: index.html)
  • --base: URL path prefix (default: root; e.g. --base /app). Pages must reference assets relatively (./style.css) or include the prefix (/app/style.css).

Examples

Use with an external API (CORS).

webadev --header "Access-Control-Allow-Origin: http://localhost:5173"

Accessing from another device (LAN) (on mobile/tablets over same WiFi).

./target/release/webadev --dir ./client --port 9000 --ip 0.0.0.0

# visit: http://<your-local-ip>:9000

Serve under a path prefix /app/.

webadev --base /app

# visit: http://127.0.0.1:<port>/app/

Library

From simplest to most control.

1. Static serving

use std::net::IpAddr;
use std::path::PathBuf;
use webadev::{Config, Server};

let dir: PathBuf = "public".into();    // directory to serve
let config = Config {
    dir,
    ip: IpAddr::from([127, 0, 0, 1]),
    port: 8080,
    headers: vec![],
    index: "index.html".into(),
    base: String::new(),
};

let server = Server::new(config).await?;   // binds; url known, not serving yet
println!("Starting development server at {}", server.url);
server.run().await?;                        // blocks until shutdown

Use 0 as config.port to let the OS pick a free port (the chosen port is visible in server.url).

Set config.base to prefix the path (e.g. /app). Empty string or / serves at the root.

2. With live reload

use std::net::IpAddr;
use std::path::PathBuf;
use tokio::sync::broadcast;
use webadev::{Config, Server, watch};

let dir: PathBuf = ".".into();           // directory to watch and serve
let (tx, _rx) = broadcast::channel(100); // keep a receiver alive so watch() can send
watch(tx.clone(), &dir)?;

let config = Config {
    dir,                                  // same directory (moved in)
    ip: IpAddr::from([127, 0, 0, 1]),
    port: 8080,
    headers: vec![],
    index: "index.html".into(),
    base: String::new(),
};

let server = Server::bind(tx, config).await?;  // watches upstream, drives reloads
server.run().await?;

The broadcast channel notifies subscribers of reload events (ReloadType, Vec<PathBuf>):

  • ReloadType::Css (CSS-only) or ReloadType::Page (full reload),
  • Vec<PathBuf>: the modified file paths.

3. Advanced: compose with your own axum router

Use the low-level bind and serve:

use std::path::PathBuf;
use tokio::sync::broadcast;
use webadev::{Config, bind, serve};

let (tx, _rx) = broadcast::channel(100);
let dir: PathBuf = ".".into();
let config = Config {
    dir,
    ip: IpAddr::from([127, 0, 0, 1]),
    port: 8080,
    headers: vec![],
    index: "index.html".into(),
    base: String::new(),
};
let (url, listener, router) = bind(tx, config).await?;
// here you can tweak the axum router
serve(listener, router).await?;

Helper

base_normalize validates and normalizes a URL path prefix with the same rules the server applies. Returns the normalized prefix (empty string for the site root), or an error.

use webadev::base_normalize;

assert_eq!(base_normalize("app/").unwrap(), "/app");
assert_eq!(base_normalize("/").unwrap(), ""); // the site root
assert!(base_normalize("/app/../x").is_err());

Feature flags

  • serve (default): server (Config, Server, bind, serve), watcher (watch, ReloadType) and base_normalize.
  • default-features = false: watcher (watch, ReloadType) and base_normalize, without the server. Does not pull Axum as a dependency.
# watcher only, no HTTP server
webadev = { version = "0.9", default-features = false }

Local installation

# clone the repo
git clone https://github.com/francoisromain/webadev.git
cd webadev

# build the project
cargo build --release

# run the server
./target/release/webadev --dir ./client --header "Access-Control-Allow-Origin: *"

# install globally from the local package
# compiles and copies the binary to `~/.cargo/bin/webadev`
cargo install --path . --locked

# use from anywhere.
# serves the current directory on 127.0.0.1:<resolved> (random free port by default)
cd ~/some/project
webadev

# update later after source changes
cargo install --path . --locked --force

Similar tools

See docs/similar-tools.md for a comparison table.