Reference

Overview

Trilha's packages and what each one does.

Package	Import	Role
`trilha`	`github.com/emersonjoe/trilha`	runtime: `App`, `Ctx`, errors, CSRF, static files, export
`h`	`github.com/emersonjoe/trilha/h`	HTML DSL
`tmpl`	`github.com/emersonjoe/trilha/tmpl`	adapter for `html/template`
`cache`	`github.com/emersonjoe/trilha/cache`	cache with expiry, tags and per-request memo
`ui`	`github.com/emersonjoe/trilha/ui`	component kit (theme compatible with shadcn/ui)
`ai`	`github.com/emersonjoe/trilha/ai`	OpenAI-compatible client, tools, agents
`ai/mcp`	`github.com/emersonjoe/trilha/ai/mcp`	MCP client and server
CLI	`github.com/emersonjoe/trilha/cmd/trilha`	`new`, `gen`, `dev`, `build`, `routes`, `export`, `audit`, `ui`

None of them depends on anything outside the standard library. Compatible with Go 1.22 or newer.

Mental model on one page#

File conventions in app/ define routes, layouts and middlewares (Conventions).
Every route function receives *trilha.Ctx (Ctx) and returns error or (h.Node, error).
Errors are values with HTTP meaning (Errors).
Form and JSON input is filled and checked by Bind (Validation).
HTML is an h.Node (h), coming from the DSL or from a template (tmpl).
trilha_gen.go wires everything and is generated by the CLI; App (App) is what it builds.

Stability#

Version 0.x: the API may change between minor versions. Breaking changes are listed in the repository's CHANGELOG.md with migration instructions.

What "the API" means is written down. The exported symbols of the packages in the table above are covered by the promise; internal/, the exact output of the CLI and the HTML the ui components produce are not. Before a covered symbol disappears it gets a Deprecated: note saying what replaces it, a line in the CHANGELOG, and at least one minor version living alongside the replacement.

The whole surface is versioned in api/current.txt, one line per symbol, and a test fails when it changes — so a removal shows up in the review instead of in your build. The rules are in API.md.