frontend

Documentation

Index

• func BuiltinFuncMap() htmpl.FuncMap
• func IsViteRunning(cfg ViteConfig) bool
• func RegisterSPA(engine *gin.Engine, cfg SPAConfig, log *slog.Logger)
• func RegisterSPAWithTemplates(engine *gin.Engine, cfg SPAConfig, log *slog.Logger)
• type AppStateBuilder
• type Assets
  • func ResolveAssets(cfg ViteConfig) Assets
• type SPAConfig
• type StateBuilder
• type ViteConfig
  • func (c ViteConfig) WithDefaults() ViteConfig

Functions

func BuiltinFuncMap

func BuiltinFuncMap() htmpl.FuncMap

BuiltinFuncMap returns the template functions go-core always provides. Applications can merge extra functions via SPAConfig.ExtraFuncs.

func IsViteRunning

func IsViteRunning(cfg ViteConfig) bool

IsViteRunning probes the Vite dev server. Uses a 2s timeout.

func RegisterSPA

func RegisterSPA(engine *gin.Engine, cfg SPAConfig, log *slog.Logger)

RegisterSPA wires template loading and the NoRoute catch-all handler on the given engine. Call this after all other routes have been registered.

The handler:

• Returns 404 JSON for any request under APIPrefix.
• Renders TemplateName for everything else, with template data: .Assets — frontend.Assets .AppState — whatever StateBuilder returns (nil if not configured) .Nonce — CSP nonce if present in gin.Context

func RegisterSPAWithTemplates

func RegisterSPAWithTemplates(engine *gin.Engine, cfg SPAConfig, log *slog.Logger)

RegisterSPAWithTemplates is an alias for RegisterSPA. SPA registration now owns template setup for the common case.

Types

type AppStateBuilder

type AppStateBuilder = StateBuilder

AppStateBuilder is kept as an alias for the SPA state builder type.

type Assets

type Assets struct {
	CSSPaths      []string
	JSPath        string
	IsDev         bool
	ViteClientURL string
}

Assets holds the resolved CSS and JS paths for the current environment.

func ResolveAssets

func ResolveAssets(cfg ViteConfig) Assets

ResolveAssets detects whether Vite is running and returns the correct asset paths for the current environment.

In dev mode it returns Vite dev server URLs. In prod mode it resolves the configured entry from Vite's manifest.

type SPAConfig

type SPAConfig struct {
	// Vite holds Vite dev server and asset resolution config.
	Vite ViteConfig

	// TemplatesPath is the glob used to load HTML templates.
	// Defaults to "frontend/templates/*.html".
	TemplatesPath string

	// TemplateName is the HTML template to render for all non-API routes.
	// Defaults to "index.html".
	TemplateName string

	// APIPrefix is the URL prefix that must NOT be caught by NoRoute.
	// Defaults to "/api".
	APIPrefix string

	// StateBuilder is optional. If provided, its return value is exposed to the
	// template as appState.
	StateBuilder StateBuilder

	// ExtraFuncs allows the application to add template functions on top of the
	// built-in toJSON helper.
	ExtraFuncs htmpl.FuncMap

	// DevMode resolves assets on every request instead of once at startup.
	// In development this should usually be true.
	DevMode bool
}

SPAConfig configures the SPA catch-all handler and template loading.

type StateBuilder

type StateBuilder func(ctx *gin.Context) any

StateBuilder builds request-scoped state that is injected into the SPA shell.

type ViteConfig

type ViteConfig struct {
	// DevServerURL is the base URL of the Vite dev server.
	// Defaults to "http://localhost:5173".
	DevServerURL string

	// Entry is the Vite entry module used by the SPA.
	// Defaults to "src/main.ts".
	Entry string

	// ManifestPath is the path to Vite's production manifest file.
	// Defaults to "./frontend/dist/.vite/manifest.json".
	ManifestPath string

	// AssetsURLPrefix is the public URL prefix under which built assets are served.
	// Defaults to "/frontend/dist".
	AssetsURLPrefix string
}

ViteConfig holds Vite dev server and production asset resolution settings.

func (ViteConfig) WithDefaults

func (c ViteConfig) WithDefaults() ViteConfig