Skip to content
typelatePublic

Repository files navigation

Muxt Go Reference

Muxt generates net/http handlers from html/template names and type-checks the templates against the Go data they render. It targets web apps that ship as one Go binary serving hypermedia from the standard library with standard hypermedia controls (forms or anchor tags), fixi, htmx, or Datastar.

A template name is the contract between the HTML and the http.Handler:

{{define "GET /article/{id} GetArticle(ctx, id)"}}
  <h1>{{.Result.Title}}</h1>
{{end}}
func (s Server) GetArticle(ctx context.Context, id int) (Article, error) { ... }

muxt generate reads the name and writes an http.Handler that calls your method. Give it the receiver type, //go:generate go tool muxt generate --use-receiver-type=Server, and it reads the method's signature, so id arrives as an int and .Result is an Article. Without the flag id is a string and .Result is any.

muxt check type-checks each template against the data it receives, so renaming a field fails the check in every template that still uses it. It covers ExecuteTemplate calls on the templates variable (the package-level *template.Template, named templates by default) with a literal template name and a statically known data type, which generated handlers always satisfy.

Install

go get -tool github.com/typelate/muxt

Call it from a directive, //go:generate go tool muxt generate, or from a shell, go tool muxt check. go.mod records the version, so everyone who builds the project runs the same muxt. For a binary on your PATH, use go install github.com/typelate/muxt@latest.

Commands read the package in the working directory; run them there or pass -C <dir> (go tool muxt -C ./web check). muxt loads packages the way the go command does, so it inherits GOWORK, GOFLAGS, and GOROOT.

Start with the Quick Start.

Template names

[METHOD ][HOST]/[PATH][ HTTP_STATUS][ CALL]

POST /user/{id} 201 CreateUser(ctx, id, form) is a standard http.ServeMux pattern plus an optional status code and method call. Template Name Syntax is the full grammar; Call Parameters and Call Results cover arguments and returns. TemplateRoutePaths type-checks URLs too: write {{$.Path.GetArticle 42}} instead of href="/article/42".

Examples

The command tests show every feature.

Commands

  • muxt generate: generate http.Handler glue (writes template_routes.go)
  • muxt check: type-check templates without generating (for CI or editor save hooks)
  • muxt list-template-calls / muxt list-template-callers: explore call sites and callers
  • muxt test-template-mutations: vary each template action and report the ones no test catches
  • muxt explore-module / muxt generate-fake-server: survey muxt packages; serve a fake server to poke at routes
  • muxt documentation [path]: print these docs and the example apps from the installed binary; --query searches them

Documentation

The documentation index lists tutorials, how-to guides, reference, and explanation.

Go Standard Library

License

Muxt: MIT

Generated code: Muxt asserts no copyright over its output. Treat generated files as your own code, under whatever license your project uses.

No warranty. Muxt and its generated output are provided "as is", without warranty of any kind, express or implied, including but not limited to warranties of merchantability, fitness for a particular purpose, and non-infringement. You are responsible for reviewing, testing, and securing any code generated by Muxt before using it. In no event shall the authors or copyright holders be liable for any claim, damages, or other liability arising from the use of Muxt or its output.

Releases

Used by

Contributors

Languages