web_spa

Okapi Web / SPA Serving

Okapi serves a front-end application (React, Vue, Svelte, Angular, …) alongside the API. Real files are served directly; any unmatched path under the prefix falls back to the index document so the client-side router takes over.

Two entry points:

o.Web(prefix, dir string, cfg ...WebConfig)        // from a directory on disk
o.WebFS(prefix string, fsys fs.FS, cfg ...WebConfig) // from any fs.FS (embed.FS, os.DirFS, …)

SPA / SPAFS / SPAConfig are deprecated aliases of Web / WebFS / WebConfig. They still work unchanged.

Register Web/WebFS after your API routes so the API keeps precedence.

Serve from Disk (development)

o := okapi.Default()

o.Get("/api/v1/users", listUsers)

// Serves ./web/index.html for "/", "/login", "/users/42", ...
o.Web("/", "./web")

o.Start()

Serve from an Embedded FS (production, single binary)

//go:embed all:web/dist
var dist embed.FS

func main() {
    o := okapi.Default()

    o.Get("/api/v1/users", listUsers)

    o.WebFS("/", dist, okapi.WebConfig{
        Root:   "web/dist", // sub-directory inside the embed.FS
        MaxAge: time.Hour,  // Cache-Control for assets
    })

    o.Start()
}

Use the all: prefix in the //go:embed directive so files beginning with _ or . (common in build output) are included.

WebConfig

Field	Type	Description
Index	string	File served for client-side routes. Defaults to index.html.
Root	string	Sub-directory inside the fs.FS holding the built app. WebFS only — ignored by Web.
Exclude	[]string	Extra path prefixes that must never fall back to the index.
DisableAutoExclude	bool	Turn off auto-excluding the top-level segment of registered routes; only Exclude is consulted.
MaxAge	time.Duration	Cache-Control max-age for asset files. The index is always no-cache.

The zero value is valid: serve index.html, auto-exclude registered API routes, no asset caching header.