x/frontend Primer
x/frontend Primer
Section titled “x/frontend Primer”Beta — API is stable within a minor version. Check Release Posture and Extension Maturity before adopting in production.
Open this page after x/* Family when the change is clearly about serving frontend assets from a Go HTTP service: mounting a static directory, serving embedded assets compiled into the binary, configuring SPA fallback routing, or managing cache headers for precompressed files.
x/frontend provides static and embedded frontend serving helpers for explicit mounting. It is transport-only and has no opinion about the frontend framework or build output format.
Start here when
Section titled “Start here when”- you are mounting a filesystem directory as a static asset path in a Plumego service
- you are serving embedded assets via
embed.FScompiled into the binary withRegisterFS - you are configuring SPA fallback routing so that unknown paths serve
index.html - you are setting cache headers and precompressed asset serving policy (
Brotli,gzip) - you are configuring content security or cache-control headers for frontend asset responses
Do not start here when
Section titled “Do not start here when”- the change is about HTTP route matching or path parameter extraction — that belongs in
router - the work is business-specific UI flows or product page logic — keep that in the frontend application
- the change introduces core bootstrap ownership or application wiring — that belongs in
coreandapp/routes.go - the work involves tenant-specific asset resolution or per-tenant theming
First files to read in the current repository
Section titled “First files to read in the current repository”x/frontend/module.yamlx/frontend/frontend.gox/frontend/mount.gox/frontend/config.gox/frontend/compression.go
Concrete ownership examples
Section titled “Concrete ownership examples”Keep it in x/frontend when the work is about | Move out when the work becomes |
|---|---|
Mounting http.Dir or embed.FS at a path with SPA fallback | route matching rules or path parameter extraction — use router |
Cache-control and Expires header policy for asset responses | CDN-level or reverse-proxy cache configuration |
Serving precompressed .br or .gz files when the client accepts them | business-specific content negotiation outside asset serving |
Fallback to index.html for SPA client-side routing | server-side rendering or dynamic page generation |
RegisterFS: serving caller-provided http.FileSystem values such as http.FS(embedFS) | frontend build tooling or asset pipeline configuration |
Why this primer exists
Section titled “Why this primer exists”Serving frontend assets from a Go service is a common pattern but easy to wire incorrectly: hidden filesystem side effects, fallback policy baked into router rules, or cache headers scattered across handlers. x/frontend centralizes these concerns in explicit, transport-only helpers so that mounting stays visible in routes.go and cache policy stays reviewable.