spa-server/README.md

einherjar/spa-server

A shield wall holds because every warrior knows their position. The SPA asks only for the wall — not for every soldier's name.

code.nochebuena.dev/einherjar/spa-server is a container-first HTTP server for single-page applications and progressive web apps. It serves static assets directly and falls back to index.html for navigation routes that do not resolve to a file — the standard SPA routing contract — while a missing asset returns 404 rather than the HTML shell.

The module ships as a ready-to-use Docker base image. Deploying a SPA to a container requires a single COPY instruction. No nginx, no custom configuration, no index.html redirect logic to maintain.

---

Container usage

FROM code.nochebuena.dev/einherjar/spa-server:v1.7.0
COPY dist/ /srv/www/

That is the complete Dockerfile for a production SPA container. It runs as an unprivileged user and serves /srv/www on port 8080.

COPY dist/ /srv/www/ is correct for Vite and CRA, which emit index.html at the root of dist/. Angular's application builder instead emits dist/<project>/browser/ (with index.html inside browser/, next to 3rdpartylicenses.txt), so copy that subdirectory — otherwise no index.html lands at the root and every request falls through to a 404:

FROM code.nochebuena.dev/einherjar/spa-server:v1.7.0
COPY dist/my-app/browser/ /srv/www/

---

Environment variables

Variable	Default	Description
EINHERJAR_SPA_PORT	8080	TCP port the server listens on
EINHERJAR_SPA_STATIC_DIR	/srv/www	Path to the directory containing index.html and assets
EINHERJAR_LOG_LEVEL	INFO	Log level: DEBUG, INFO, WARN, ERROR

---

Health endpoint

GET /health returns 200 OK with a JSON body consistent with all Einherjar health responses:

{"status":"UP","components":{}}

503 Service Unavailable is never returned — if the process is alive, it is healthy. Wire /health directly to your container liveness and readiness probes.

---

Routing behaviour

Request	Result
/app.js — file exists	Served directly with correct Content-Type
/assets/logo.png — file exists	Served directly
/dashboard — no file, Accept: text/html	index.html served (SPA router handles it)
/ — directory	index.html served (directory listing is disabled)
/main.js — no file, has an extension	404 — a missing asset is not masked as HTML
/api/x — no file, Accept: application/json	404 — a non-HTML client is not handed index.html

The fallback to index.html is deliberately scoped to navigation requests (no file extension, and Accept includes text/html or */*). A request for a missing asset returns 404 instead of index.html, so a broken deploy fails at the first request rather than delivering the SPA shell as JavaScript (Unexpected token '<').

---

Caching

Cache-Control is set per file, correct for Vite, CRA and Angular alike:

File	Cache-Control
index.html	no-cache — revalidated every load, so a new deploy is never masked
Service workers (ngsw.json, ngsw-worker.js, sw.js, service-worker.js, safety-worker.js, workbox-*.js)	no-cache — a client is never pinned to a superseded release
Content-hashed assets (main.4f8a2b1c.js, index-DkJf3x9a.js, …)	public, max-age=31536000, immutable
Everything else (favicon.ico, icons/, verbatim assets)	public, max-age=3600

A hashed filename is detected by a trailing hash-like token (≥8 alphanumerics including a digit) before the extension — a heuristic whose only failure mode is a missed year-long cache, never staleness.

Every response also carries X-Content-Type-Options: nosniff.

---

Dependency graph

contracts  (zero dependencies)
    ↑
  core
    ↑
spa-server  (contracts, core, stdlib only)

No external dependencies beyond the Go standard library.

---

Verification

cd spa-server/
go build ./...
go vet ./...
go test ./...
gofmt -l .

---

A shield wall holds because every warrior knows their position. The SPA asks only for the wall — not for every soldier's name.