https://github.com/typelate/muxt
"html/template" Enhancing Tools for Hypermedia Web Applications
https://github.com/typelate/muxt
generate go go-template golang htmx hypermedia-driven-application interface-description-language template type-check webapps
Last synced: about 1 month ago
JSON representation
"html/template" Enhancing Tools for Hypermedia Web Applications
- Host: GitHub
- URL: https://github.com/typelate/muxt
- Owner: typelate
- License: agpl-3.0
- Created: 2024-08-05T06:58:23.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-01-14T08:19:40.000Z (about 2 months ago)
- Last Synced: 2026-01-14T11:14:40.235Z (about 2 months ago)
- Topics: generate, go, go-template, golang, htmx, hypermedia-driven-application, interface-description-language, template, type-check, webapps
- Language: Go
- Homepage:
- Size: 2.47 MB
- Stars: 6
- Watchers: 1
- Forks: 1
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Muxt [](https://pkg.go.dev/github.com/typelate/muxt) [](https://github.com/typelate/muxt/actions/workflows/go.yml)
**Generate HTTP handlers from html/template definitions.**
Declare routes in template names using `http.ServeMux` patterns. Muxt analyzes receiver methods and generates handlers that parse parameters to match method signatures.
You can use `muxt generate` to generate `http.Handler` glue code or you can just use `muxt check`, `muxt list-template-calls`, and `muxt list-template-callers` to find bugs and more safely refactor your `"text/template"` or `"html/template"` source code.
## Syntax
Standard `http.ServeMux` pattern:
```
[METHOD ][HOST]/[PATH]
```
Muxt extends this with optional status codes and method calls:
```
[METHOD ][HOST]/[PATH][ HTTP_STATUS][ CALL]
```
## Example
Define a template with a route pattern and method call:
```gotemplate
{{define "GET /{id} GetUser(ctx, id)"}}
{{with $err := .Err}}
{{$err.Error}}
{{else}}
{{.Result.Name}}
{{.Result.Email}}
{{end}}
{{end}}
```
Implement the receiver method:
```go
func (s Server) GetUser(ctx context.Context, id int) (User, error) {
return s.db.GetUser(ctx, id) // id automatically parsed from string
}
```
Run `muxt generate --use-receiver-type=Server` to generate HTTP handlers.
## How It Works
**Template names define the contract.** Muxt analyzes method signatures using `go/types` and generates handlers that:
- Parse path parameters to method argument types (`string`, `int`, `bool`, custom `TextUnmarshaler`)
- Bind form data to struct fields with validation
- Inject request context, `*http.Request`, or `http.ResponseWriter` when named
- Handle errors and return values through `TemplateData[T]`
- Set HTTP status codes from template names, return values, or error types
**No (additional) runtime reflection.** All type checking happens at generation time. The generated code uses only `net/http` and `html/template` from the standard library.
## Installation
```bash
go install github.com/typelate/muxt@latest
```
Or add it to your project's module `go get -tool github.com/typelate/muxt` (note the project [license documentation](#License)).
## Quick Start
1. Create a template file `index.gohtml`:
```gotemplate
{{define "GET / Home(ctx)"}}
{{.Result}}
{{end}}
```
2. Add generation directives to `main.go`:
```go
//go:embed *.gohtml
var templateFS embed.FS
//go:generate muxt generate --use-receiver-type=Server
var templates = template.Must(template.ParseFS(templateFS, "*.gohtml"))
type Server struct{}
func (s Server) Home(ctx context.Context) string {
return "Hello, Muxt!"
}
```
3. Generate handlers and run:
```bash
go generate && go run .
```
## Examples
The [command tests](./cmd/muxt/testdata) were intended to be readable examples of muxt behavior.
- **[Local example](./docs/examples/simple/)** - Complete application with tests ([pkg.go.dev](https://pkg.go.dev/github.com/typelate/muxt/docs/examples/simple/hypertext))
- **[Sortable Example](http://github.com/typelate/sortable-example)** - Interactive HTMX-enabled table row sorting
- **[HTMX Template](https://github.com/typelate/htmx-template)** - Full HTMX integration patterns
## Documentation
Comprehensive documentation organized by task:
- **[Getting Started Tutorial](docs/tutorials/getting-started.md)** - Build your first Muxt application
- **[How-To Guides](docs/how-to/)** - Integrate, test, use HTMX, add logging
- **[Reference](docs/reference/)** - CLI, syntax, parameters, type checking
- **[Explanation](docs/explanation/)** - Design philosophy, patterns, decisions
See the [full documentation index](docs/) for all available resources.
## Using with AI Assistants
Paste these prompts into Claude Code or other AI assistants when building hypermedia apps:
| Prompt | Use Case |
|--------|----------|
| [muxt-quick.md](docs/prompts/muxt-quick.md) | Syntax lookup, minimal context |
| [muxt-guide.md](docs/prompts/muxt-guide.md) | Comprehensive guide for building apps |
| [muxt-complete.md](docs/prompts/muxt-complete.md) | Edge cases, testing patterns, advanced usage |
Start with `muxt-guide.md` for most sessions. Use `muxt-quick.md` when context is limited.
## License
Muxt generator: [GNU AGPLv3](LICENSE)
Generated code: [MIT License](https://choosealicense.com/licenses/mit/) - The Go code generated by Muxt is not covered by AGPL. It is provided as-is without warranty. Use it freely in your projects.