servio
An HTTP server for static files, with live reload, built with Axum. It is designed for local development: files are not cached, and the browser refreshes when they change.
Features
- Live reload, debounced by 200 ms
- Gzip and Brotli compression
- Single-page app (SPA) fallback
- Optional long-term caching for published assets
- Safe defaults: localhost only, no caching, hidden files blocked
- Protection against serving files through symlinks outside the chosen directory
- Security headers including
X-Content-Type-Options,X-Frame-Options, andReferrer-Policy
Install
Rust 1.88 or newer is required.
To install the latest development version:
To install from a local clone:
Quick start
Run servio in the directory you want to serve, then open the address shown
in the terminal.
# Serve the current directory at http://127.0.0.1:3030
# Serve another directory on port 8080
# Fall back to index.html for SPA routes such as /users/123
# Make the server reachable from other devices on your network
# Open the browser as well
Options
| Option | Default | Description |
|---|---|---|
-d, --dir <DIR> |
. |
Directory to serve |
-p, --port <PORT> |
3030 |
Port to use |
--host <HOST> |
127.0.0.1 |
Address to listen on |
--spa |
off | Serve index.html when a page route matches no file |
--no-reload |
off | Disable file watching and browser refreshes |
--poll |
off | Find changes by looking at the files, once a second |
--cache-assets |
off | Cache files under /assets/ for one year |
--open |
off | Open the address in the browser |
--ignore <PATTERN> |
none | Do not refresh the browser for changes matching this pattern; may be given more than once |
If you do not specify a port and 3030 is busy, servio tries the next available port through 3039 and prints the selected address. If you specify a port, servio uses that exact port or exits with an error.
--open opens the address in your usual browser, or in the one BROWSER
names. That variable may be a whole command, with %s where the address goes:
BROWSER="firefox --new-window %s"
It may also name several, tried in turn until one opens the address, parted by
: (; on Windows); one that stops at once with an error is passed over for
the next. Quote anything with a space in it, a path or a flag's value:
BROWSER="firefox:'/Applications/Firefox.app/Contents/MacOS/firefox' %s"
A quote counts anywhere in a word, as it does in a shell, so a path with an apostrophe in it has to be quoted whole.
If no browser can be opened, or the one named stops at once with an error,
servio says so and keeps serving. With --poll, the browser opens once the
first look at the files is done.
Live reload
Saving a file refreshes the browser. servio ignores changes in hidden
directories, target, node_modules, and common editor temporary files.
--ignore adds patterns of your own, for a build that writes logs or a cache
next to the pages:
A pattern is matched against the path below the served directory, written with
/, and against every directory above it, so cache covers everything in
cache/. A pattern with no / in it matches a name at any depth, as it does in
.gitignore; one with a / starts from the served directory, so build/*.log
is exactly one directory deep, and /cache is only the cache at the top. *
stops at a /; ** crosses any number of directories, and tmp/** covers
tmp itself as well. On macOS and Windows, where the disk does not tell
Build.LOG from build.log, neither does a pattern. The files are still
served, and --poll still reads them: the pattern only decides what refreshes
the browser.
Naming files does not name the folder holding them. With *.log, a build that
creates out/ afresh each run refreshes the browser once, for the new folder;
out/** covers the folder as well.
Patterns used on every run belong in a file called .servioignore in the
served directory, one to a line, with # starting a comment:
# what the build writes next to the pages
*.log
cache
The file is read once, when the server starts. Being hidden, it is never
served, and editing it does not refresh the browser. Its patterns and those
from --ignore apply together, and the banner says how many it added.
Live reload continues working when a build replaces the served directory, or moves it aside and back. On macOS, changing file permissions may also trigger one refresh because of how the operating system reports file events.
When saving a file changes nothing
Live reload normally waits for the operating system to report a change. Some
filesystems never report one: network shares, folders shared with a virtual
machine, and directories mounted into a container. There, --poll finds
changes by looking at the files itself, once a second:
Every look reads every file in the served directory and compares its contents,
because a poll compares write times only to the whole second, and two saves
within one second of each other would otherwise look like one. So
--poll notices a change up to a second later than the ordinary watcher, and
costs far more while it waits. Use it only where the ordinary watcher stays
silent, and point it at the build output rather than the whole project tree, or
every look will read node_modules as well.
On Windows there is one more reason to poll. A build that changes thousands of
files in the same instant can overflow the room the system keeps for reporting
them. The system's watcher then stops without a word, and nothing refreshes
until servio is started again. Where builds are that large, --poll cannot
lose the watch.
Links are not followed. The server refuses to hand out anything outside the served directory, so a link leading out cannot change what the browser sees, and one leading back in points at files each look reads anyway.
Neither --poll nor --ignore can be combined with --no-reload, which
turns off watching altogether.
Single-page apps
With --spa, missing page routes fall back to index.html so the client-side
router can handle them. Missing scripts, stylesheets, images, and anything
under /assets/ still return 404, making broken asset paths easy to spot.
If index.html disappears while the server is running, such as during a build
that clears the output directory, servio says so in the terminal. It says it
once each time the page goes missing rather than once per route, so a broken
build does not leave every address returning 404 without explanation.
Without --spa, every missing path returns 404.
Serving a published site
Disable live reload and enable caching for content-hashed assets:
--cache-assets gives files under /assets/ a one-year immutable cache
policy. Other files are revalidated so visitors still receive updated pages.
When exposing servio to a network, serve only the intended build directory.
Hidden paths are blocked apart from .well-known, which certificate renewal
needs, and symlinks may point only within the served directory. Each
subdirectory also uses a file watch while live reload is on, so serving a large
project tree can exhaust the operating system's watch limit.
Development
Run the test suite with:
See CHANGELOG.md for version history and RELEASE.md for the release process.
License
MIT — see LICENSE.