Muxt

"html/template" Enhancing Tools for Hypermedia Web Applications

Generate Convert Improve

Install / Use

/learn @typelate/Muxt

About this skill

Quality Score

0/100

README

Muxt

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.

Muxt commands include:

muxt generate to generate http.Handler glue (see template_routes.go for the output)
muxt list template routes
muxt check to find bugs and more safely refactor your "text/template" or "html/template" source code
muxt list-template-calls list all call sites for a template (omit flag --patterns to list all call sites)
muxt list-template-callers list all callers for a template (omit flag --patterns to list all callers for all templates)

Syntax

Standard http.ServeMux pattern:

[METHOD ][HOST]/[PATH]

Muxt extends this with optional status codes and method calls:

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

For example, "GET /article/{id} GetArticle(ctx, id)" means: handle GET requests to /article/{id}, call GetArticle with the request context and the id path parameter, render the template with the result.

How It Works

Template names define the contract between your HTML and your Go code. Without Muxt, this connection relies on connascence of name through raw strings: templates.ExecuteTemplate(w, "user-profile", data) uses a string that must match a template name, and {{.Name}} must match a field on whatever data happens to be. A typo in either place is a runtime error.

Muxt upgrades this to connascence of type. It uses go/types to verify at generation time that:

The method named in the template (GetArticle) exists on the receiver type with the correct signature
Path parameters (id) can be parsed to the method's parameter types (string, int, bool, custom TextUnmarshaler)
The template body's field access (.Result.Title) is valid for the method's return type
Form parameters (form) match a concrete struct type with the right fields
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[R, T]
Set HTTP status codes from template names, return values, or error types

If any of these are wrong, go generate or muxt check fails with a clear error pointing to the template. No runtime surprises.

TemplateRoutePaths extends this to URLs: instead of hardcoding href="/article/42", templates use {{$.Path.GetArticle 42}}. If the route pattern changes, the generated method signature changes, and the compiler catches every stale reference.

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

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).

Quick Start

Create a template file index.gohtml:

{{define "GET / Home(ctx)"}}
<!DOCTYPE html>
<html>
<body><h1>{{.Result}}</h1></body>
</html>
{{end}}

Add generation directives to main.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!"
}

Generate handlers and run:

go generate && go run .

Key elements:

//go:embed *.gohtml embeds template files into the binary
//go:generate muxt generate tells go generate to run Muxt
--use-receiver-type=Server tells Muxt to look up method signatures on Server
The templates variable must be package-level (Muxt finds it via static analysis)

Example

Define a template with a route pattern and method call:

{{define "GET /{id} GetUser(ctx, id)"}}
  {{with $err := .Err}}
    <div class="error" data-type="{{printf `%T` $err}}">{{$err.Error}}</div>
  {{else}}
    <h1>{{.Result.Name}}</h1>
    <p>{{.Result.Email}}</p>
  {{end}}
{{end}}

Implement the receiver method:

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.

Examples

The command tests were intended to be readable examples of muxt behavior.

Local example - Complete application with tests (pkg.go.dev)
Sortable Example - Interactive HTMX-enabled table row sorting
HTMX Template - Full HTMX integration patterns

Documentation

Reference - CLI, syntax, parameters, type checking
Explanation - Design philosophy, patterns, decisions

See the full documentation index for all available resources.

Go Standard Library

html/template — Template syntax, functions, escaping
net/http — ServeMux routing patterns, Handler interface
embed — File embedding directives
log/slog — Structured logging (used by generated handlers)
Routing Enhancements for Go 1.22 — ServeMux pattern syntax that Muxt extends

Using with AI Assistants

Claude Code skills for working with Muxt codebases:

| Skill | Use Case | |-------|----------| | explore-from-route | Trace from a URL path to its template and receiver method | | explore-from-method | Find which routes and templates use a receiver method | | explore-from-error | Trace an error message back to its handler and template | | explore-repo-overview | Map all routes, templates, and the receiver type | | template-driven-development | Create new templates and receiver methods using TDD | | forms | Form creation, struct binding, validation, and accessible form HTML | | debug-generation-errors | Diagnose and fix muxt generate / muxt check errors | | refactoring | Rename methods, change patterns, move templates safely | | htmx | Explore, develop, and test HTMX interactions | | integrate-existing-project | Add Muxt to an existing Go web application | | sqlc | Use Muxt with sqlc for type-safe SQL + HTML | | goland-gotype | Add gotype comments for GoLand IDE support (GoLand-only) | | maintain-tools | Install and update muxt, gofumpt, counterfeiter, and other tools |

Install as Claude Code skills:

for d in docs/skills/*/; do cp -r "$d" ~/.claude/skills/"$(basename "$d")"; done

License

Muxt generator: GNU AGPLv3

Generated code: MIT License - The Go code generated by Muxt is not covered by AGPL. It is provided as-is without warranty. Use it freely in your projects.

Star History

Related Skills

node-connect

351.8k

Diagnose OpenClaw node connection and pairing failures for Android, iOS, and macOS companion apps

xurl

351.8k

A CLI tool for making authenticated requests to the X (Twitter) API. Use this skill when you need to post tweets, reply, quote, search, read posts, manage followers, send DMs, upload media, or interact with any X API v2 endpoint.

frontend-design

110.9k

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

openai-whisper-api

351.8k

Transcribe audio via OpenAI Audio Transcriptions API (Whisper).