Serving Static Files with Axum

20 min read

Quick Overview

Almost every web service eventually needs to hand a browser some bytes off disk — a built single-page app (SPA), an index.html, CSS/JS bundles, images, a robots.txt. In Express you reach for the built-in express.static middleware; in Axum you mount a tower-http file-serving service — ServeDir for a whole directory tree, ServeFile for one specific file. This page shows how to wire those services into a Router, how to combine them with real API routes, and how to do the one thing every SPA needs: a fallback to index.html so client-side routes like /dashboard/settings load the app instead of returning a 404.

Note: This page uses axum 0.8 (current stable 0.8.9) and tower-http 0.6 (0.6.11). The current stable toolchain is Rust 1.96.0 on the latest stable edition (2024); cargo new selects it automatically. Servers start with axum::serve(listener, app) and a tokio::net::TcpListener. File-serving lives behind tower-http’s opt-in fs feature.

TypeScript/JavaScript Example

In Express, static file serving is a single line: express.static returns a middleware that, for each request, tries to find a matching file under a root directory and streams it, complete with the right Content-Type, Last-Modified, ETag, conditional-request (304) handling, and an optional maxAge cache header. Anything it does not find, it passes to the next middleware.

1
// server.ts — Express 5
2
// npm install express
3
// npm install -D @types/express
4
import express from "express";
5

6
const app = express();
7

8
// 1) Serve everything under ./public at the URL root.
9
//    GET /            -> public/index.html (default index)
10
//    GET /style.css   -> public/style.css
11
//    GET /js/app.js   -> public/js/app.js
12
app.use(express.static("public", { maxAge: "1h" }));
13

14
// 2) A real API route still works — it is just another middleware.
15
app.get("/api/health", (_req, res) => {
16
  res.json({ status: "ok" });
17
});
18

19
app.listen(3000, () => {
20
  console.log("listening on http://127.0.0.1:3000");
21
});

Running this and probing it (with Node v22’s built-in fetch) shows the behavior a TypeScript developer relies on:

1
/            -> 200 text/html; charset=UTF-8 cc=public, max-age=3600
2
/api/health  -> 200 application/json; charset=utf-8 cc=null
3
/missing.html -> 404 text/html; charset=utf-8 cc=null

So express.static (a) serves index.html for a directory, (b) applies the maxAge cache header, and (c) returns a 404 for files it cannot find. For a single-page app you typically add one more line so that unknown paths return index.html:

1
// SPA fallback: any GET that did not match a file or API route gets index.html,
2
// so the client-side router (React Router, etc.) can take over.
3
import path from "node:path";
4

5
app.get("/{*splat}", (_req, res) => {
6
  res.sendFile(path.resolve("public/index.html"));
7
});

Three jobs, then: serve a directory, serve one file, and fall back to the app shell. Axum has a dedicated, well-tested service for each.

Rust Equivalent

The file-serving services live in tower-http, gated behind the fs feature. Add the dependencies in a fresh project (cargo new static-demo):

1
cargo add axum
2
cargo add tokio --features full
3
cargo add tower-http --features fs

1
# Cargo.toml (resolved versions)
2
[dependencies]
3
axum = "0.8"
4
tokio = { version = "1", features = ["full"] }
5
tower-http = { version = "0.6", features = ["fs"] }

Note: tower-http’s features are opt-in. ServeDir/ServeFile need fs; the same fs feature also enables .precompressed_gzip() and friends shown later. You do not need a separate compression-gzip feature just to serve pre-built .gz files.

Here is the direct equivalent of the Express example — ServeDir for the directory, ServeFile for a single named file, and an ordinary handler for the API:

1
use axum::{routing::get, Json, Router};
2
use serde_json::{json, Value};
3
use tower_http::services::{ServeDir, ServeFile};
4

5
async fn health() -> Json<Value> {
6
    Json(json!({ "status": "ok" }))
7
}
8

9
fn app() -> Router {
10
    // Serve a single file at a specific route.
11
    let favicon = ServeFile::new("public/favicon.ico");
12

13
    // Serve a whole directory tree.
14
    let static_files = ServeDir::new("public");
15

16
    Router::new()
17
        // Real API routes take priority because they are matched first.
18
        .route("/api/health", get(health))
19
        // `route_service` mounts a tower Service (not a handler) at one path.
20
        .route_service("/favicon.ico", favicon)
21
        // Anything not matched above is looked up on disk under ./public.
22
        .fallback_service(static_files)
23
}
24

25
#[tokio::main]
26
async fn main() {
27
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3007").await.unwrap();
28
    println!("listening on http://{}", listener.local_addr().unwrap());
29
    axum::serve(listener, app()).await.unwrap();
30
}

This also needs serde_json (cargo add serde_json). Running it and probing with curl -i produces this real output:

1
$ curl -s -i http://127.0.0.1:3007/
2
HTTP/1.1 200 OK
3
content-type: text/html
4
accept-ranges: bytes
5
last-modified: Mon, 01 Jun 2026 12:13:21 GMT
6
content-length: 65
7

8
<!doctype html><title>Home</title><h1>Hello from index.html</h1>
9

10
$ curl -s -i http://127.0.0.1:3007/assets/app.css
11
HTTP/1.1 200 OK
12
content-type: text/css
13
accept-ranges: bytes
14
last-modified: Mon, 01 Jun 2026 12:13:22 GMT
15
content-length: 33
16

17
body { font-family: system-ui; }
18

19
$ curl -s -i http://127.0.0.1:3007/api/health
20
HTTP/1.1 200 OK
21
content-type: application/json
22
content-length: 15
23

24
{"status":"ok"}
25

26
$ curl -s -i http://127.0.0.1:3007/does-not-exist.html
27
HTTP/1.1 404 Not Found
28
content-length: 0

Notice what ServeDir did for free, exactly like express.static: it guessed text/html and text/css from the file extension, set Last-Modified and Accept-Ranges, served index.html for the / request, and returned a 404 for the missing file. You wrote zero of that logic.

Detailed Explanation

`ServeDir` — a directory of files

ServeDir::new("public") builds a tower Service (not an Axum handler) that, for each request, maps the request path onto a path under public/ and streams the file if it exists. It handles, out of the box:

MIME type inference from the file extension (text/css, text/javascript, image/png, …).
index.html for directories — a request for / (or /docs/) serves public/index.html (or public/docs/index.html). This is on by default; disable it with .append_index_html_on_directories(false).
Conditional requests — it honors If-Modified-Since and If-None-Match and replies 304 Not Modified (more on this below).
Range requests — Accept-Ranges: bytes plus partial 206 responses for video scrubbing and resumable downloads.
Path traversal protection — a request for /../../etc/passwd is rejected; you cannot escape the served root.

Because ServeDir is a Service and not a fn, you mount it with fallback_service, route_service, or nest_service — never with get(...), which expects a handler (see Common Pitfalls).

`ServeFile` — one specific file

ServeFile::new("public/favicon.ico") is the single-file cousin: every request routed to it serves that one file, ignoring the request path. It is what you use to pin a known file to a known route (/favicon.ico, /robots.txt) and, crucially, it is the building block of the SPA fallback below.

Routing precedence: API first, files last

The order in the Router matters conceptually, not lexically: Axum matches declared routes (/api/health, /favicon.ico) before consulting the fallback service. So real endpoints always win, and only requests that match no route reach ServeDir. The curl /api/health output above proves it: the JSON handler answered, not a file lookup.

Tip: fallback_service takes a Service; the plain fallback takes a handler. Use fallback_service(ServeDir::new(...)) for files and fallback(handler) for a custom 404 handler. They are mutually exclusive on a given router — pick the one that matches what you are mounting.

The SPA fallback: serving `index.html` for unknown routes

A single-page app ships a built bundle (often under dist/) and does its own routing in the browser. When a user reloads on /dashboard/settings, the server must return the app shell (index.html) so the JS router can render that view — returning a 404 would break deep links and refreshes. There are two ways to express this in tower-http, and they differ in one important detail: the status code.

1
use axum::Router;
2
use tower_http::services::{ServeDir, ServeFile};
3

4
fn app() -> Router {
5
    // Serve real files from ./dist; for any missing path, fall back to the SPA
6
    // shell. `.fallback` here is ServeDir's OWN fallback (a tower-http method),
7
    // and it preserves a 200 status — what an SPA wants.
8
    let spa = ServeDir::new("dist")
9
        .fallback(ServeFile::new("dist/index.html"));
10

11
    Router::new().fallback_service(spa)
12
}
13

14
#[tokio::main]
15
async fn main() {
16
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3009").await.unwrap();
17
    println!("listening on http://{}", listener.local_addr().unwrap());
18
    axum::serve(listener, app()).await.unwrap();
19
}

A deep link returns the shell with a 200 OK — verified:

1
$ curl -s -i http://127.0.0.1:3009/settings/profile
2
HTTP/1.1 200 OK
3
content-type: text/html
4
accept-ranges: bytes
5
last-modified: Mon, 01 Jun 2026 12:17:41 GMT

ServeDir also has a .not_found_service(...) method. It looks almost identical but behaves differently — it serves the file with the 404 status that triggered the fallback. That is correct for a custom 404 page, but wrong for an SPA shell, where you want a 200. Keep the two straight:

Method	Use it for	Resulting status
`ServeDir::fallback(ServeFile::new("index.html"))`	SPA app shell on deep links	200 OK
`ServeDir::not_found_service(ServeFile::new("404.html"))`	A real custom error page	404 Not Found

This is a genuinely easy mistake to make; the names suggest they are interchangeable, but the status code is exactly the thing your CDN, SEO crawler, and uptime monitor care about.

Key Differences

Concern	Express (`express.static`)	Axum (`tower-http`)
What it is	A middleware function in the chain	A tower `Service` mounted on the router
Mounting	`app.use(express.static(dir))`	`.fallback_service(ServeDir::new(dir))`
Single file	`res.sendFile(path)` in a handler	`ServeFile::new(path)` via `route_service`
MIME type	Inferred (via `mime` package)	Inferred (via `mime_guess`)
Conditional GET / 304	Built in	Built in
Range requests	Built in	Built in
SPA fallback	An extra catch-all `app.get("/{*splat}", …)`	`ServeDir::fallback(ServeFile::new("index.html"))`
Cache-Control	`{ maxAge }` option	A separate `SetResponseHeaderLayer` (tower)
Pre-compressed assets	Needs `serve-static` config / a plugin	`.precompressed_gzip()` etc., built in
Missing root dir	Errors per-request	Silently 404s per-request (no startup check)

The mental shift for a TypeScript developer: in Express, serving files is middleware in a pipeline. In Axum, it is a self-contained service that you compose into the router tree — the same composable Service abstraction that powers handlers, middleware layers, and nested routers (see middleware.md for the tower model and routing.md for nest/fallback). One consequence: a cache header is not an option on the file service; it is a layer you wrap around it, because layers are the universal way to transform any response in tower.

Caching: add a `Cache-Control` layer

ServeDir already sets Last-Modified and answers conditional requests, but it deliberately does not set Cache-Control — that is a policy decision you make per route. Add it with SetResponseHeaderLayer from tower-http’s set-header feature (cargo add tower-http --features fs,set-header):

1
use axum::{http::header, Router};
2
use http::HeaderValue;
3
use tower_http::services::ServeDir;
4
use tower_http::set_header::SetResponseHeaderLayer;
5

6
fn app() -> Router {
7
    // Build artifacts are content-hashed (app.4f2a1c.js), so they never change
8
    // under a given name -> cache for a year, immutable.
9
    let cache_forever = SetResponseHeaderLayer::overriding(
10
        header::CACHE_CONTROL,
11
        HeaderValue::from_static("public, max-age=31536000, immutable"),
12
    );
13

14
    Router::new()
15
        .nest_service("/assets", ServeDir::new("dist/assets"))
16
        .layer(cache_forever)
17
}
18

19
#[tokio::main]
20
async fn main() {
21
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3013").await.unwrap();
22
    println!("listening on http://{}", listener.local_addr().unwrap());
23
    axum::serve(listener, app()).await.unwrap();
24
}

This needs http (cargo add http). The header appears, and conditional requests still produce a real 304 — verified:

1
$ curl -s -i http://127.0.0.1:3013/assets/main.js
2
HTTP/1.1 200 OK
3
content-type: text/javascript
4
last-modified: Mon, 01 Jun 2026 12:17:41 GMT
5
cache-control: public, max-age=31536000, immutable
6

7
$ curl -s -i -H "If-Modified-Since: Mon, 01 Jun 2026 12:17:41 GMT" \
8
       http://127.0.0.1:3013/assets/main.js
9
HTTP/1.1 304 Not Modified

That 304 was produced by ServeDir itself, comparing the request’s If-Modified-Since against the file’s modification time — exactly what express.static does, with no code from you.

Serving pre-compressed assets

If your build step already emits main.js.gz next to main.js, ServeDir can serve the smaller pre-compressed file to clients that advertise Accept-Encoding: gzip, avoiding on-the-fly compression entirely. This is part of the fs feature:

1
use axum::Router;
2
use tower_http::services::ServeDir;
3

4
fn app() -> Router {
5
    // For a request to /assets/main.js with `Accept-Encoding: gzip`, serve
6
    // main.js.gz if it exists; otherwise serve main.js uncompressed.
7
    let assets = ServeDir::new("dist/assets").precompressed_gzip();
8
    Router::new().nest_service("/assets", assets)
9
}
10

11
#[tokio::main]
12
async fn main() {
13
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3014").await.unwrap();
14
    println!("listening on http://{}", listener.local_addr().unwrap());
15
    axum::serve(listener, app()).await.unwrap();
16
}

Verified — the gzip request gets content-encoding: gzip and the smaller body, a request without Accept-Encoding gets the plain file:

1
$ curl -s -D - -o /dev/null -H "Accept-Encoding: gzip" \
2
       http://127.0.0.1:3014/assets/main.js
3
HTTP/1.1 200 OK
4
content-type: text/javascript
5
accept-ranges: bytes
6
content-encoding: gzip
7
content-length: 55
8

9
$ curl -s -D - -o /dev/null http://127.0.0.1:3014/assets/main.js
10
HTTP/1.1 200 OK
11
content-type: text/javascript

There are matching .precompressed_br() (Brotli) and .precompressed_zstd() methods. For on-the-fly compression of dynamic responses (your JSON APIs), use the separate CompressionLayer instead — that is covered in middleware.md.

Common Pitfalls

1. Mounting a `ServeDir` with `get(...)`

get(...)/post(...) expect a handler (an async fn). ServeDir is a tower Service, so passing it to get does not compile:

1
use axum::{routing::get, Router};
2
use tower_http::services::ServeDir;
3

4
fn app() -> Router {
5
    // does not compile (error[E0277]: ServeDir: Handler<_, _> is not satisfied)
6
    Router::new().route("/assets", get(ServeDir::new("dist")))
7
}

The real compiler error names the missing trait:

1
error[E0277]: the trait bound `ServeDir: Handler<_, _>` is not satisfied
2
  --> src/main.rs:7:40
3
   |
4
 7 |     Router::new().route("/assets", get(ServeDir::new("dist")))
5
   |                                    --- ^^^^^^^^^^^^^^^^^^^^^ the trait `Handler<_, _>` is not implemented for `ServeDir`
6
   |                                    |
7
   |                                    required by a bound introduced by this call

The fix is to mount the service with the _service family of methods: route_service("/assets/{*path}", ServeDir::new("dist")), nest_service("/assets", ServeDir::new("dist")), or fallback_service(ServeDir::new("dist")).

2. SPA fallback returns 404 instead of 200

Using .not_found_service(ServeFile::new("dist/index.html")) does serve the shell, but with a 404 status (it is meant for error pages). Browsers usually still render it, but CDNs may refuse to cache it, SEO crawlers treat the route as missing, and uptime checks flag the page as down. For an SPA shell use ServeDir::fallback(...), which preserves the 200. See the table in The SPA fallback.

3. Relative paths resolve against the process working directory, not the binary

ServeDir::new("dist") is relative to the current working directory of the running process, not the location of the compiled binary. Run the same binary from a different directory (or from a container with a different WORKDIR) and it will quietly fail to find your files. Worse, a missing root directory does not panic at startup — it just returns 404 for every request:

1
$ curl -s -i http://127.0.0.1:3015/anything   # ServeDir points at a non-existent dir
2
HTTP/1.1 404 Not Found
3
content-length: 0

In production, prefer an absolute path derived from configuration (e.g. a STATIC_DIR env var), or embed the assets into the binary (see Best Practices). See deployment.md for the Docker WORKDIR angle.

4. The SPA fallback swallows your API 404s

If /api/* shares the same catch-all index.html fallback, a request to a misspelled API endpoint like /api/todoss returns the HTML app shell with a 200 — and your frontend’s fetch then tries to JSON.parse("<!doctype html>…") and throws a confusing error. Keep API routes under their own nested router with a JSON 404 fallback, and only let the SPA fallback catch non-API paths. The Real-World example below does exactly this.

5. Expecting `Cache-Control` for free

ServeDir sets Last-Modified and does 304s, but never sets Cache-Control. If you expected express.static’s maxAge behavior, add a SetResponseHeaderLayer as shown above — there is no implicit caching policy.

Best Practices

Separate cache policies by route. Long-cache content-hashed bundles (/assets/* → max-age=31536000, immutable), but serve index.html with no-cache (or a short max-age) so users pick up new deployments. Apply different SetResponseHeaderLayers to different sub-routers.
Put the API on its own nested router with a JSON 404. Mount it with nest("/api", api_router()) so a mistyped endpoint returns JSON, not the SPA shell (pitfall #4).
Use ServeDir::fallback(ServeFile::new("index.html")) for the SPA shell so deep links return 200.
Resolve the static directory from config / an absolute path in production, never a bare relative string that depends on the launch directory.
Add TraceLayer while developing so you can see which requests hit a file vs. the fallback (see middleware.md).
Consider embedding assets into the binary for single-file deploys. Crates like rust-embed (with an axum integration) bake dist/ into the executable at compile time, eliminating the working-directory problem and producing one self-contained binary — handy for scratch-based Docker images. ServeDir from disk is simpler when you deploy the assets alongside the binary or behind a reverse proxy / CDN.
Let a reverse proxy or CDN serve static files in production when you can. Nginx/Cloudflare in front of your Axum app can serve /assets/* directly; Axum’s ServeDir is then a convenient fallback and the source of truth in development. See deployment.md.

Real-World Example

A production-shaped app that combines all the pieces: a JSON API under /api (with its own JSON 404), aggressively-cached fingerprinted assets under /assets, an SPA shell fallback that returns 200 for deep links, and request tracing. Dependencies: cargo add axum tokio --features full; cargo add tower-http --features fs,set-header,trace; cargo add http serde_json tracing tracing-subscriber.

1
use axum::{
2
    http::{header, StatusCode},
3
    routing::get,
4
    Json, Router,
5
};
6
use http::HeaderValue;
7
use serde_json::{json, Value};
8
use tower_http::{
9
    services::{ServeDir, ServeFile},
10
    set_header::SetResponseHeaderLayer,
11
    trace::TraceLayer,
12
};
13

14
// --- API handlers ---------------------------------------------------------
15

16
async fn list_todos() -> Json<Value> {
17
    Json(json!([{ "id": 1, "title": "Wire up the SPA" }]))
18
}
19

20
// Any /api/* path that no route matched is a genuine 404 -> JSON, not HTML.
21
async fn api_fallback() -> (StatusCode, Json<Value>) {
22
    (StatusCode::NOT_FOUND, Json(json!({ "error": "no such endpoint" })))
23
}
24

25
// --- Router assembly -------------------------------------------------------
26

27
fn api_router() -> Router {
28
    Router::new()
29
        .route("/todos", get(list_todos))
30
        .fallback(api_fallback)
31
}
32

33
fn static_router() -> Router {
34
    // Content-hashed build artifacts never change under a given name.
35
    let cache_forever = SetResponseHeaderLayer::overriding(
36
        header::CACHE_CONTROL,
37
        HeaderValue::from_static("public, max-age=31536000, immutable"),
38
    );
39
    let assets = ServeDir::new("dist/assets");
40

41
    // Everything else falls back to the SPA shell with a 200 status, so deep
42
    // links such as /dashboard/settings load the app rather than a 404.
43
    let spa = ServeDir::new("dist").fallback(ServeFile::new("dist/index.html"));
44

45
    Router::new()
46
        .nest_service("/assets", assets)
47
        .layer(cache_forever)
48
        .fallback_service(spa)
49
}
50

51
fn build_app() -> Router {
52
    Router::new()
53
        .nest("/api", api_router())
54
        .merge(static_router())
55
        .layer(TraceLayer::new_for_http())
56
}
57

58
#[tokio::main]
59
async fn main() {
60
    tracing_subscriber::fmt().with_target(false).compact().init();
61
    let app = build_app();
62
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3016").await.unwrap();
63
    tracing::info!("listening on http://{}", listener.local_addr().unwrap());
64
    axum::serve(listener, app).await.unwrap();
65
}

Exercising every path proves each policy fires correctly — real output:

1
$ curl -s -i http://127.0.0.1:3016/api/todos
2
HTTP/1.1 200 OK
3
content-type: application/json
4
[{"id":1,"title":"Wire up the SPA"}]
5

6
$ curl -s -i http://127.0.0.1:3016/dashboard/settings   # SPA deep link
7
HTTP/1.1 200 OK
8
content-type: text/html
9

10
$ curl -s -D - -o /dev/null http://127.0.0.1:3016/assets/main.js
11
HTTP/1.1 200 OK
12
content-type: text/javascript
13
cache-control: public, max-age=31536000, immutable
14

15
$ curl -s -i http://127.0.0.1:3016/api/nope            # misspelled API route
16
HTTP/1.1 404 Not Found
17
content-type: application/json
18
{"error":"no such endpoint"}

Four routes, four distinct behaviors, all composed from small services and layers: the API answers JSON, the SPA deep link returns the shell at 200, the asset carries a year-long cache header, and the mistyped API path returns JSON 404 instead of leaking the HTML shell.

Note: merge combines two routers at the same level; nest("/api", …) mounts a router under a path prefix. Because declared routes are matched before fallbacks, /api/* is handled by api_router and never reaches the SPA fallback. See routing.md.

Exercises

Exercise 1: A documentation site with a custom 404 page

Difficulty: Beginner

Objective: Serve a directory of static HTML and return a styled custom 404 page (with a 404 status) for missing files.

Instructions: Create a server that serves everything under ./site at the URL root. When a requested file does not exist, return ./site/404.html with a 404 Not Found status (not a 200). Use the method whose name signals “this is an error page”, not the SPA-shell method.

Solution

1
use axum::Router;
2
use tower_http::services::{ServeDir, ServeFile};
3

4
fn app() -> Router {
5
    // `.not_found_service` serves the file WITH the 404 status that triggered
6
    // the miss — correct for a real error page.
7
    let files = ServeDir::new("site")
8
        .not_found_service(ServeFile::new("site/404.html"));
9
    Router::new().fallback_service(files)
10
}
11

12
#[tokio::main]
13
async fn main() {
14
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3017").await.unwrap();
15
    println!("listening on http://{}", listener.local_addr().unwrap());
16
    axum::serve(listener, app()).await.unwrap();
17
}

A request for a missing path returns the custom page with a real 404 — verified:

1
$ curl -s -i http://127.0.0.1:3017/whatever
2
HTTP/1.1 404 Not Found
3
content-type: text/html
4
accept-ranges: bytes
5
content-length: 69
6

7
<!doctype html><title>Not Found</title><h1>404 — nothing here</h1>

Contrast with ServeDir::fallback(ServeFile::new(...)), which would have returned 200 — that variant is for SPA shells, not error pages.

Exercise 2: Cache assets aggressively, but never cache the HTML shell

Difficulty: Intermediate

Objective: Apply two different Cache-Control policies to two sub-routers.

Instructions: Serve content-hashed bundles under /assets with public, max-age=31536000, immutable, and serve the SPA shell (and all deep links) with no-cache so users always pick up new deployments. Mount each sub-router with its own SetResponseHeaderLayer, then combine them. Requires cargo add tower-http --features fs,set-header and cargo add http.

Solution

1
use axum::{http::header, Router};
2
use http::HeaderValue;
3
use tower_http::services::{ServeDir, ServeFile};
4
use tower_http::set_header::SetResponseHeaderLayer;
5

6
fn assets_router() -> Router {
7
    let long_cache = SetResponseHeaderLayer::overriding(
8
        header::CACHE_CONTROL,
9
        HeaderValue::from_static("public, max-age=31536000, immutable"),
10
    );
11
    Router::new()
12
        .nest_service("/assets", ServeDir::new("dist/assets"))
13
        .layer(long_cache)
14
}
15

16
fn shell_router() -> Router {
17
    let no_cache = SetResponseHeaderLayer::overriding(
18
        header::CACHE_CONTROL,
19
        HeaderValue::from_static("no-cache"),
20
    );
21
    // SPA fallback returns index.html at 200 for any unmatched path.
22
    let spa = ServeDir::new("dist").fallback(ServeFile::new("dist/index.html"));
23
    Router::new().fallback_service(spa).layer(no_cache)
24
}
25

26
fn app() -> Router {
27
    assets_router().merge(shell_router())
28
}
29

30
#[tokio::main]
31
async fn main() {
32
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3018").await.unwrap();
33
    println!("listening on http://{}", listener.local_addr().unwrap());
34
    axum::serve(listener, app()).await.unwrap();
35
}

/assets/* carries the year-long immutable header; the shell carries no-cache. Because each layer wraps only its own sub-router, the two policies never collide. The /assets routes are declared first, so they win over the SPA fallback.

Exercise 3: A unified app — API JSON 404 plus SPA shell fallback

Difficulty: Advanced

Objective: Build the routing tree that prevents the SPA fallback from swallowing API 404s (pitfall #4).

Instructions: Create one app where (1) GET /api/ping returns {"pong":true}, (2) any other /api/* path returns a JSON 404, and (3) every non-API path returns the SPA shell dist/index.html with a 200. Verify that /api/oops returns JSON 404 while /some/spa/route returns HTML 200. Requires cargo add axum tokio --features full; cargo add tower-http --features fs; cargo add serde_json.

Solution

1
use axum::{http::StatusCode, routing::get, Json, Router};
2
use serde_json::{json, Value};
3
use tower_http::services::{ServeDir, ServeFile};
4

5
async fn ping() -> Json<Value> {
6
    Json(json!({ "pong": true }))
7
}
8

9
async fn api_fallback() -> (StatusCode, Json<Value>) {
10
    (StatusCode::NOT_FOUND, Json(json!({ "error": "no such endpoint" })))
11
}
12

13
fn app() -> Router {
14
    // /api/* lives in its own nested router with a JSON 404, so a mistyped
15
    // endpoint never falls through to the HTML shell.
16
    let api = Router::new()
17
        .route("/ping", get(ping))
18
        .fallback(api_fallback);
19

20
    // The SPA shell catches everything that is not an /api route.
21
    let spa = ServeDir::new("dist").fallback(ServeFile::new("dist/index.html"));
22

23
    Router::new()
24
        .nest("/api", api)
25
        .fallback_service(spa)
26
}
27

28
#[tokio::main]
29
async fn main() {
30
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3008").await.unwrap();
31
    println!("listening on http://{}", listener.local_addr().unwrap());
32
    axum::serve(listener, app()).await.unwrap();
33
}

Verified behavior — the API path returns JSON 404, the SPA route returns the HTML shell at 200:

1
$ curl -s -i http://127.0.0.1:3008/api/ping
2
HTTP/1.1 200 OK
3
content-type: application/json
4
{"pong":true}
5

6
$ curl -s -i http://127.0.0.1:3008/api/missing
7
HTTP/1.1 404 Not Found
8
content-type: application/json
9
{"error":"no such endpoint"}
10

11
$ curl -s -i http://127.0.0.1:3008/settings/profile
12
HTTP/1.1 200 OK
13
content-type: text/html
14
<!doctype html><title>SPA</title><div id="root">SPA shell</div>...

Note: The nest("/api", …) boundary is what keeps API 404s as JSON — without it, a mistyped endpoint would fall through to the SPA shell. The shell uses ServeDir::fallback(...), so deep links return 200; switch it to .not_found_service(...) only if you specifically want a 404 status on the shell.

Serving Static Files with Axum

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

ServeDir — a directory of files

ServeFile — one specific file

Routing precedence: API first, files last

The SPA fallback: serving index.html for unknown routes

Key Differences

Caching: add a Cache-Control layer

Serving pre-compressed assets

Common Pitfalls

1. Mounting a ServeDir with get(...)

2. SPA fallback returns 404 instead of 200

3. Relative paths resolve against the process working directory, not the binary

4. The SPA fallback swallows your API 404s

5. Expecting Cache-Control for free

Best Practices

Real-World Example

Further Reading

Exercises

Exercise 1: A documentation site with a custom 404 page

Exercise 2: Cache assets aggressively, but never cache the HTML shell

Exercise 3: A unified app — API JSON 404 plus SPA shell fallback

`ServeDir` — a directory of files

`ServeFile` — one specific file

The SPA fallback: serving `index.html` for unknown routes

Caching: add a `Cache-Control` layer

1. Mounting a `ServeDir` with `get(...)`

5. Expecting `Cache-Control` for free