SPA

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.

​

Overview

• React/Vue/Angular app hosting
• Client-side routing support
• HTML5 pushState routing

​

Installation

import "github.com/go-mizu/mizu/middlewares/spa"

​

Quick Start

app := mizu.New()

// Serve SPA from ./dist directory
app.Use(spa.New("./dist"))

// API routes still work
app.Get("/api/users", listUsers)

​

Configuration

​

Options

​

Examples

​

Basic Usage

app.Use(spa.New("./dist"))

​

From Embedded FS

//go:embed dist/*
var distFS embed.FS

app.Use(spa.WithFS(distFS, "dist"))

​

Skip API Routes

app.Use(spa.WithOptions(spa.Options{
    Root:      "./dist",
    SkipPaths: []string{"/api", "/health"},
}))

​

Custom Index

app.Use(spa.WithOptions(spa.Options{
    Root:  "./public",
    Index: "app.html",
}))

​

With Prefix

app.Use(spa.WithOptions(spa.Options{
    Root:   "./dist",
    Prefix: "/app",
}))
// SPA available at /app/*

​

How It Works

1. Request comes in for /users/123
2. Check if file exists at ./dist/users/123
3. If file exists: serve it
4. If not: serve ./dist/index.html
5. Client-side router handles /users/123

​

API Reference

​

Functions

// New creates SPA middleware for directory
func New(root string) mizu.Middleware

// WithFS creates SPA middleware for fs.FS
func WithFS(fsys fs.FS, root string) mizu.Middleware

// WithOptions creates SPA middleware with configuration
func WithOptions(opts Options) mizu.Middleware

​

Complete Example

package main

import (
    "embed"
    "github.com/go-mizu/mizu"
    "github.com/go-mizu/mizu/middlewares/spa"
)

//go:embed dist/*
var distFS embed.FS

func main() {
    app := mizu.New()

    // API routes
    api := app.Group("/api")
    api.Get("/users", listUsers)
    api.Post("/users", createUser)

    // Serve SPA for everything else
    app.Use(spa.WithOptions(spa.Options{
        FS:        distFS,
        Root:      "dist",
        SkipPaths: []string{"/api"},
    }))

    app.Listen(":3000")
}

​

Technical Details

​

Implementation Overview

​

Path Resolution Process

1. Ignore Path Check: Checks if the request path matches any configured IgnorePaths (default: /api)
2. Prefix Handling: If a Prefix is configured, strips it from the path before file resolution
3. File Existence Check: Determines if the requested path corresponds to an actual file:
   • For fs.FS: Uses fs.Stat() to check file existence
   • For directory path: Uses os.Stat() with filepath.Join()
4. File Serving: If file exists and is not a directory, serves it with appropriate cache headers
5. Index Fallback: If file doesn’t exist, serves the index file (default: index.html)

​

Cache Control Strategy

• Static Assets: Configurable via MaxAge option (default: 0/no cache)
  • Sets Cache-Control: public, max-age=<MaxAge> header
  • Recommended: Long cache duration (e.g., 31536000 for 1 year) for versioned assets
• Index File: Configurable via IndexMaxAge option (default: 0)
  • When IndexMaxAge = 0: Sets Cache-Control: no-cache, no-store, must-revalidate
  • When IndexMaxAge > 0: Sets Cache-Control: public, max-age=<IndexMaxAge>
  • No-cache default ensures users always get latest SPA routing configuration

​

File Serving Details

• Automatic MIME type detection based on file extension
• HTTP range request support for partial content
• Proper Last-Modified header handling
• Efficient byte streaming with io.ReadSeeker

​

Security Considerations

• All file paths are cleaned using filepath.Clean() to prevent directory traversal attacks
• The middleware only serves files from the configured root directory or filesystem
• Directory listings are disabled (directories trigger index fallback)

​

Best Practices

• Define API routes before SPA middleware
• Use embedded FS for portable deployments
• Skip API and health check paths
• Set proper cache headers for static assets
• Use long cache durations for static assets with content hashing
• Keep index.html uncached to ensure SPA updates are immediately available

​

Testing

​

Related Middlewares

• static - Static file serving
• favicon - Favicon serving
• embed - Embedded filesystem