structpages: Instructions file for Claude Code

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. It renders any value with Render(context.Context, io.Writer) error; the examples use gsx, and templ and html/template also work.

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, examples/todo, examples/blog, ...

# Generated .x.go files are committed, so this runs as is (typically on :8080)
go run .

# After editing .gsx sources: regenerate and format. Each example pins the gsx
# CLI as a `tool` dependency; the repo-root gsx.toml registers the
# structpages url/id/target filters for every example.
go tool gsx generate .
go tool gsx fmt -w .

Required Tools

• Go 1.26 or later for the examples (the library itself needs Go 1.24)

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() component method (most common), a Props method (Props-only pages), or a ServeHTTP method (form actions, redirects). Promoted (embedded) methods are skipped.