> ## Documentation Index > Fetch the complete documentation index at: https://docs.go-mizu.dev/llms.txt > Use this file to discover all available pages before exploring further. # API Reference > Complete API reference for the frontend middleware. Complete reference for the frontend middleware API. ## Functions ### New Creates frontend middleware with default options. ```go theme={null} func New(root string) mizu.Middleware ``` **Parameters:** * `root` (string): Directory containing built frontend files **Returns:** `mizu.Middleware` **Example:** ```go theme={null} app.Use(frontend.New("./dist")) ``` ### Dev Creates development-only middleware that proxies to dev server. ```go theme={null} func Dev(devServerURL string) mizu.Middleware ``` **Parameters:** * `devServerURL` (string): URL of frontend dev server **Returns:** `mizu.Middleware` **Example:** ```go theme={null} app.Use(frontend.Dev("http://localhost:5173")) ``` ### WithFS Creates production middleware with embedded filesystem. ```go theme={null} func WithFS(fsys fs.FS) mizu.Middleware ``` **Parameters:** * `fsys` (fs.FS): Embedded filesystem containing frontend files **Returns:** `mizu.Middleware` **Example:** ```go theme={null} //go:embed all:dist var distFS embed.FS dist, _ := fs.Sub(distFS, "dist") app.Use(frontend.WithFS(dist)) ``` ### WithOptions Creates middleware with full configuration. ```go theme={null} func WithOptions(opts Options) mizu.Middleware ``` **Parameters:** * `opts` (Options): Configuration options **Returns:** `mizu.Middleware` **Example:** ```go theme={null} app.Use(frontend.WithOptions(frontend.Options{ Mode: frontend.ModeAuto, Root: "./dist", DevServer: "http://localhost:5173", IgnorePaths: []string{"/api"}, })) ``` ## Types ### Options Configuration for the frontend middleware. ```go theme={null} type Options struct { // Mode determines serving behavior Mode Mode // Production options Root string FS fs.FS Index string Prefix string IgnorePaths []string CacheControl CacheConfig // Development options DevServer string DevServerTimeout time.Duration ProxyWebSocket bool // Advanced options Manifest string InjectEnv []string InjectMeta map[string]string SecurityHeaders bool SourceMaps bool ServiceWorker string ErrorHandler func(*mizu.Ctx, error) error NotFoundHandler func(*mizu.Ctx) error } ``` **Fields:** **Mode:** * Type: `Mode` * Default: `ModeAuto` * Description: Controls how middleware operates **Root:** * Type: `string` * Default: `"dist"` * Description: Directory containing built frontend files **FS:** * Type: `fs.FS` * Default: `nil` * Description: Embedded filesystem (takes precedence over Root) **Index:** * Type: `string` * Default: `"index.html"` * Description: Fallback file for SPA routing **Prefix:** * Type: `string` * Default: `""` * Description: URL prefix for serving frontend **IgnorePaths:** * Type: `[]string` * Default: `[]string{"/api", "/health", "/metrics"}` * Description: Paths that bypass frontend middleware **CacheControl:** * Type: `CacheConfig` * Default: See CacheConfig defaults * Description: Caching behavior configuration **DevServer:** * Type: `string` * Default: `"http://localhost:5173"` * Description: URL of frontend dev server **DevServerTimeout:** * Type: `time.Duration` * Default: `30 * time.Second` * Description: Timeout for dev server requests **ProxyWebSocket:** * Type: `bool` * Default: `true` * Description: Enable WebSocket proxying for HMR **Manifest:** * Type: `string` * Default: `""` * Description: Path to build manifest file **InjectEnv:** * Type: `[]string` * Default: `nil` * Description: Environment variables to inject into HTML **InjectMeta:** * Type: `map[string]string` * Default: `nil` * Description: Meta tags to inject into HTML **SecurityHeaders:** * Type: `bool` * Default: `true` * Description: Enable default security headers **SourceMaps:** * Type: `bool` * Default: `false` * Description: Allow serving source map files **ServiceWorker:** * Type: `string` * Default: `""` * Description: Path to service worker file **ErrorHandler:** * Type: `func(*mizu.Ctx, error) error` * Default: `nil` * Description: Custom error handler **NotFoundHandler:** * Type: `func(*mizu.Ctx) error` * Default: `nil` * Description: Handler called before SPA fallback ### Mode Operating mode for the middleware. ```go theme={null} type Mode string const ( ModeDev Mode = "dev" ModeProduction Mode = "production" ModeAuto Mode = "auto" ) ``` **Values:** * `ModeDev`: Always proxy to dev server * `ModeProduction`: Always serve static files * `ModeAuto`: Auto-detect based on environment ### CacheConfig Caching behavior configuration. ```go theme={null} type CacheConfig struct { HashedAssets time.Duration UnhashedAssets time.Duration HTML time.Duration Patterns map[string]time.Duration } ``` **Fields:** **HashedAssets:** * Type: `time.Duration` * Default: `365 * 24 * time.Hour` (1 year) * Description: Cache duration for files with content hash **UnhashedAssets:** * Type: `time.Duration` * Default: `7 * 24 * time.Hour` (1 week) * Description: Cache duration for files without hash **HTML:** * Type: `time.Duration` * Default: `0` (no-cache) * Description: Cache duration for HTML files **Patterns:** * Type: `map[string]time.Duration` * Default: `nil` * Description: Custom cache durations for file patterns **Example:** ```go theme={null} CacheConfig{ HashedAssets: 365 * 24 * time.Hour, UnhashedAssets: 7 * 24 * time.Hour, HTML: 0, Patterns: map[string]time.Duration{ "*.woff2": 30 * 24 * time.Hour, "*.png": 14 * 24 * time.Hour, }, } ``` ## Manifest API ### LoadManifest Loads a build manifest from filesystem. ```go theme={null} func LoadManifest(fsys fs.FS, path string) (*Manifest, error) ``` **Parameters:** * `fsys` (fs.FS): Filesystem containing manifest * `path` (string): Path to manifest file **Returns:** * `*Manifest`: Loaded manifest * `error`: Error if loading fails **Example:** ```go theme={null} manifest, err := frontend.LoadManifest(distFS, ".vite/manifest.json") ``` ### Manifest Methods ```go theme={null} // Get output file for entry point func (m *Manifest) Entry(name string) string // Get URL for asset func (m *Manifest) Asset(path string) string // Get module preload paths func (m *Manifest) Preloads(entry string) []string // Get CSS files for entry func (m *Manifest) CSS(entry string) []string // Generate script tag func (m *Manifest) ScriptTag(entry string) template.HTML // Generate CSS tags func (m *Manifest) CSSTags(entry string) template.HTML // Generate preload tags func (m *Manifest) PreloadTags(entry string) template.HTML // Generate all tags (CSS + preloads + script) func (m *Manifest) EntryTags(entry string) template.HTML // Get template helper functions func (m *Manifest) ViewHelpers() template.FuncMap ``` ## Injection Functions ### InjectEnv Injects environment variables into HTML. ```go theme={null} func InjectEnv(html []byte, vars []string) []byte ``` **Parameters:** * `html` (\[]byte): HTML content * `vars` (\[]string): Environment variable names to inject **Returns:** Modified HTML with injected script ### InjectMeta Injects meta tags into HTML. ```go theme={null} func InjectMeta(html []byte, meta map[string]string) []byte ``` **Parameters:** * `html` (\[]byte): HTML content * `meta` (map\[string]string): Meta tags (name → content) **Returns:** Modified HTML with injected meta tags ### InjectPreload Injects preload link tags into HTML. ```go theme={null} func InjectPreload(html []byte, assets []PreloadAsset) []byte ``` **Parameters:** * `html` (\[]byte): HTML content * `assets` (\[]PreloadAsset): Assets to preload **Returns:** Modified HTML with preload tags ## Constants ### Default Values ```go theme={null} const ( DefaultRoot = "dist" DefaultIndex = "index.html" DefaultDevServer = "http://localhost:5173" DefaultDevTimeout = 30 * time.Second DefaultHashedCache = 365 * 24 * time.Hour // 1 year DefaultUnhashedCache = 7 * 24 * time.Hour // 1 week DefaultHTMLCache = 0 // no-cache ) ``` ### Default Ignore Paths ```go theme={null} var DefaultIgnorePaths = []string{"/api", "/health", "/metrics"} ``` ### Default Security Headers ```go theme={null} var DefaultSecurityHeaders = map[string]string{ "X-Content-Type-Options": "nosniff", "X-Frame-Options": "SAMEORIGIN", "X-XSS-Protection": "1; mode=block", "Referrer-Policy": "strict-origin-when-cross-origin", } ``` ## Next Steps Configuration guide Framework adapters Code examples