Skip to main content

Introduction

structpages is a Go web framework library that defines routes via struct tags and methods on top of http.ServeMux. It minimises boilerplate for HTML-first apps using Templ and HTMX, and gives you type-safe URL generation and dependency injection without giving up the standard library.

Status​

Beta. The API has settled and the library is battle-tested in production, carrying medium-to-large applications. Remaining breaking changes before v1 will be rare and called out in release notes.

Why structpages​

If you've built a Go web app with http.ServeMux, you've written code like:

mux.HandleFunc("GET /products/{productId}", handleProductGet)
mux.HandleFunc("POST /products/{productId}/comments", handleProductCommentCreate)
mux.HandleFunc("DELETE /products/{productId}/comments/{commentId}", handleProductCommentDelete)

That works, but the route structure lives only in string literals. structpages lets you express the same hierarchy as Go structs, so the router and your handler types stay in lockstep:

type product struct {
    comments `route:"/comments Comments"`
}

type productPages struct {
    product `route:"/products/{productId} Product"`
}

Each page renders through a Props method (loads data) and a Page method (a Templ component), or handles the request imperatively with a handler method (ServeHTTP) — whichever fits the request shape. URLs are generated by structpages.URLFor(ctx, product{}) rather than string concatenation, and the structpages-lint analyzer catches dangling references at build time.

How a request flows​

For a rendering page: route match → Props method (with a RenderTarget injected to pick the region) → page component render — the full Page for normal loads, or a single partial for HTMX requests targeting that region's id. A handler method (ServeHTTP) bypasses this pipeline and responds imperatively.

What's next​

  • Quick Start — a minimal working example end-to-end.
  • Concepts — the vocabulary: pages, page components, props, partials.
  • Routing — full route tag syntax and nesting rules.
  • Page Response Patterns — choosing between Props/Page and ServeHTTP shapes.