structpages CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Structpages is a Go web framework library that provides struct-based routing. It integrates with Go's standard http.ServeMux and provides a declarative way to define routes using struct tags. The framework is designed to reduce boilerplate code when building web pages and components, with built-in support for the Templ templating engine.

Status: Beta (API settled; battle-tested in production by medium-to-large applications)

Development Commands

Testing

# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run a specific test
go test -run TestName ./...

# Run tests with verbose output
go test -v ./...

Working with Examples

# Navigate to an example directory
cd examples/simple  # or examples/htmx or examples/todo

# Install dependencies
go mod download

# Generate Go code from Templ files (required before running)
# Each example pins the templ CLI as a `tool` dep, so `go tool` resolves the
# correct version automatically — no global install needed.
go tool templ generate -include-version=false

# Run the example server (typically on :8080)
go run main.go

# Watch mode for Templ files during development
go tool templ generate -include-version=false --watch

Required Tools

• Go 1.24 or later (for the tool directive in example go.mod files)

Architecture Overview

Core Components

1. Router System: Built on top of http.ServeMux, the router parses struct tags to create routes

   • struct_pages.go: Mount, StructPages, options, and request dispatch
   • parse.go: Parses struct tags like route:"/path Title", builds the page tree, handles DI matching
   • page_node.go: PageNode struct and tree traversal (All, FullRoute)

2. Struct-Based Routing Pattern: Routes are defined as struct fields with route tags

   type pages struct {
       product `route:"/product Product"`
       team    `route:"POST /team Team"`
   }
   

   Each leaf page handles requests via one of: a Page() templ method (most common), a Props method (Props-only pages), or a ServeHTTP method (form actions, redirects). Promoted (embedded) methods are skipped.