spa

spa

import "github.com/brpaz/lib-go/spa"

Package spa provides an [http.Handler] that serves single-page applications.

Static assets are served directly from an io/fs.FS; all other request paths fall back to the index file so that client-side routing works without server-side route configuration.

Basic usage

//go:embed dist
var distFS embed.FS

sub, _ := fs.Sub(distFS, "dist")
handler := spa.Handler(sub)

Runtime environment injection

If your index file contains a placeholder string, WithEnvVars replaces it with a JSON object at request time:

handler := spa.Handler(sub,
    spa.WithEnvVars("__FRONTEND_ENV__", map[string]any{
        "API_URL": os.Getenv("API_URL"),
    }),
)

Custom options

handler := spa.Handler(sub,
    spa.WithIndexFile("shell.html"),
    spa.WithIndexCacheControl("no-cache"),
    spa.WithNotFoundHandler(http.NotFoundHandler()),
)

Index

• func Handler(fsys fs.FS, opts ...Option) http.Handler
• type Option
  • func WithEnvVars(placeholder string, vars map[string]any) Option
  • func WithIndexCacheControl(value string) Option
  • func WithIndexFile(name string) Option
  • func WithNotFoundHandler(h http.Handler) Option
  • func WithStaticCacheControl(value string) Option

func Handler

func Handler(fsys fs.FS, opts ...Option) http.Handler

Handler returns an [http.Handler] that serves a single-page application from fsys. Static assets are served directly; all other paths are handled by the configured not-found handler (default: serve the index file).

type Option

Option configures a SPA handler.

type Option func(*options)

func WithEnvVars

func WithEnvVars(placeholder string, vars map[string]any) Option

WithEnvVars injects runtime environment variables into the index file. Every occurrence of placeholder in the index file is replaced with a JSON-encoded representation of vars before the response is written.

func WithIndexCacheControl

func WithIndexCacheControl(value string) Option

WithIndexCacheControl sets the Cache-Control header on index file responses. Defaults to "no-cache, no-store, must-revalidate".

func WithIndexFile

func WithIndexFile(name string) Option

WithIndexFile sets the path within the FS used as the SPA entry point. Defaults to "index.html".

func WithNotFoundHandler

func WithNotFoundHandler(h http.Handler) Option

WithNotFoundHandler sets the handler called when a requested path does not exist as a static asset. Defaults to serving the index file (SPA fallback).

func WithStaticCacheControl

func WithStaticCacheControl(value string) Option

WithStaticCacheControl sets the Cache-Control header on static asset responses. For SPAs with content-hashed filenames, "public, max-age=31536000, immutable" is typical. If unset, no Cache-Control header is added (http.FileServerFS handles ETags/Last-Modified).

Generated by gomarkdoc