Single Page Applications (SPA)

HTTPX provides native Single Page Application (SPA) routing, automatically resolving static assets and falling back to index.html for client-side routing.

SPA Fallback Configuration

Modern client-side frameworks (React, Vue, Svelte, Solid, Angular) rely on the HTML5 History API (pushState). When a user refreshes deep URLs like /dashboard/settings, the server must serve index.html rather than 404 Not Found.

const std = @import("std");
const httpx = @import("httpx");

pub fn main() !void {
    var gpa: std.heap.DebugAllocator(.{}) = .init;
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();
    const io = std.Io.Threaded.global_single_threaded.io();

    var server = try httpx.Server.init(allocator, io, .{ .port = 8080 });
    defer server.deinit();

    // API routes take precedence (register code routes before the SPA mount)
    try server.get("/api/status", statusHandler);

    // SPA fallback: serves existing files from ./dist, or falls back to index.html
    try server.spa("/", "./dist");

    server.run();
}

fn statusHandler(ctx: *httpx.Context) anyerror!httpx.Response {
    _ = ctx;
    return .{ .status = 200, .body = "{\"status\":\"ok\"}", .contentType = "application/json" };
}

Resolution Flow

1. Match API routes first.
2. Check if the request path maps to a physical file in ./dist (e.g. /assets/app.js, /favicon.ico).
3. If not found and request accepts text/html, serve ./dist/index.html with status 200.

Related

• Web: Static Files
• Example: SPA Fallback