servio
HTTP server for static files, with live reload, built with axum. Made for local development: nothing is cached, and the browser refreshes when a file changes.
Features
- Live reload — the browser refreshes when you save a file (it waits 200 ms, so one save is one refresh)
- Nothing is cached — every response says
Cache-Control: no-store, so the browser always shows your latest edit.--cache-assetsturns this around for a published site - Compression — gzip and Brotli
- Single-page apps — with
--spa, an address that matches no file servesindex.html, so the app can handle its own links - Security headers —
X-Content-Type-Options,X-Frame-Options,Referrer-Policy - Hidden files stay hidden — anything with a dot-prefixed name, such as
.envor.git/config, returns 404, however the address is written..well-knownis the exception - Local by default — reachable only from this machine unless you pass
--host
Installation
Or build from a clone:
&&
Usage
# Serve current directory on port 3030
# Serve a specific directory on a custom port
# Single-page app: an address like /users/123 serves index.html
# Reach the server from another device (phone, tablet, VM)
Options
| Flag | Default | Description |
|---|---|---|
--dir, -d |
. |
Directory to serve |
--port, -p |
3030 |
Port to listen on |
--host |
127.0.0.1 |
Address to listen on |
--spa |
off | Serve index.html when the address matches no file |
--no-reload |
off | Do not watch for changes, and do not refresh the browser |
--cache-assets |
off | Let the browser keep files under /assets/ for a year |
What refreshes the page, and what does not
Saving a file refreshes the browser. Changes inside .git, target,
node_modules and other build and version-control directories do not, nor do
the scratch files editors write while you type (vim swap files, emacs
autosaves, JetBrains temporary copies), nor the hidden files the server will
not send in the first place. Reading a file is not a change either, so loading
a page does not make it reload itself.
Live reload survives a build that replaces the served directory, whether it deletes and recreates it or renames it away and writes a new one in its place. The server says so and refreshes the page, because anything written while it was not watching went unseen.
On macOS, changing a file's permissions refreshes the page once. macOS reports the changes to a file as a running total, so a permission change arrives carrying the file's creation with it and the two cannot be told apart. Linux and Windows stay quiet.
Addresses that match no file
Without --spa, they return 404, as a static site should.
With --spa, only requests that ask for a page fall back to index.html; a
missing script, stylesheet or image still returns 404, so a typo in a src
attribute stays visible instead of arriving as a page of HTML.
Serving a published site
The defaults are for working on a site: nothing is cached and the browser refreshes itself. Two flags turn that off for a site you are publishing.
--no-reload stops the watching and leaves the page alone: no script is added
and no connection is held open. --cache-assets tells the browser to keep
files under /assets/ for a year, since a build gives those names a hash of
their contents and the file at such an address never changes. Everything else
is checked on each visit, so a new page is never missed, and a browser that
already has the file is told so instead of being sent it again.
Before you open it to the network
Two things to know before pointing --host 0.0.0.0 at a directory you care
about. Symbolic links are followed, including ones leading outside the served
directory. And every subdirectory costs one file-watch, so serving a tree with
node_modules in it can exhaust the system limit — serve the build output
rather than the project root.
Requirements
Rust 1.88 or newer.
Tests
The unit tests cover the rules for which file events mean a page changed, which addresses are refused, and how one directory is told from another. The rest start the real binary on a temporary directory and talk HTTP to it. Every push runs the whole suite on Linux, macOS and Windows.
License
MIT — see LICENSE.