# Trilha

> A Next.js-style web framework for Go: a folder under app/ is a route, HTML is written in Go, and nothing outside the standard library is imported.

This is the documentation index in plain text. Every entry below is one page; the whole documentation concatenated is at /trilha/llms-full.txt.

## Learn

- [Quick start](/trilha/learn): From zero to a page in the browser in five minutes, and what happened at each step.
- [Pages and routes](/trilha/learn/pages-and-routes): How folders become URLs, including dynamic segments, catch-all and groups.
- [Nested layouts](/trilha/learn/layouts): One layout per folder, from the innermost to the outermost, and how the title travels between them.
- [HTML with the h package](/trilha/learn/html-with-h): Elements as functions, escaping by default, conditionals, lists and when to use templates.
- [Forms](/trilha/learn/forms): POST in the same page.go, automatic CSRF protection and the redirect-after-write pattern.
- [API routes](/trilha/learn/api): route.go with one function per HTTP method, JSON in and out, and errors with status codes.
- [Data and cache](/trilha/learn/data): Where the data comes from, how long an answer is worth keeping, and what knocks it down — with cache.Do, tags and cache.Once.
- [Middleware](/trilha/learn/middleware): Intercept a subtree of routes, pass values to pages and protect areas.
- [Security](/trilha/learn/security): What Trilha protects by default, how to adjust it, and what remains your responsibility.
- [Health and observability](/trilha/learn/observability): Liveness and readiness probes, metrics in the Prometheus format and log correlation, taking care not to turn monitoring into a leak.
- [Authentication with Entra ID, Keycloak, Cognito and Clerk](/trilha/learn/authentication): OpenID Connect login with PKCE, signed session, roles and federated logout, with no external dependency and no password in your database.
- [UI kit](/trilha/learn/ui-kit): Trilha's default component kit, compatible with shadcn/ui themes, and how it becomes yours to customize.
- [Interactivity](/trilha/learn/interactivity): Swap one piece of the page and submit a form without a reload, from the same handler that serves the whole page.
- [AI and agents](/trilha/learn/ai-and-agents): Call a model, give tools to an agent, hand the conversation over between agents, use and expose MCP, and stream the answer.
- [Examples](/trilha/learn/examples): Complete apps in examples/, from basic to complex, and what each one teaches.
- [Testing](/trilha/learn/testing): A test client in the framework itself: one request, a whole session, CSRF that just works.
- [Development and production](/trilha/learn/dev-and-production): What trilha dev does under the hood, how to publish a binary and how to configure through environment variables.
- [Troubleshooting](/trilha/learn/troubleshooting): Errors that show up in the first minutes and what each one means.

## Reference

- [Overview](/trilha/reference): Trilha's packages and what each one does.
- [File conventions](/trilha/reference/conventions): Complete table of what each file and folder name in app/ means.
- [Ctx](/trilha/reference/ctx): Everything a route function can do with the request context.
- [Package h](/trilha/reference/h): Reference for the HTML DSL: nodes, elements, attributes and control flow.
- [Package tmpl](/trilha/reference/tmpl): Use html/template inside the pages and layouts pipeline.
- [Errors](/trilha/reference/errors): The error values Trilha understands and how each one becomes a response.
- [Validation](/trilha/reference/validation): The validate tag, the rules per type, your own rules and the messages Bind returns.
- [App and Config](/trilha/reference/app): What the generated file builds and what you can adjust in setup.go.
- [Security](/trilha/reference/security): Complete configuration of headers, proxies, rate limiting, signed cookies and events.
- [Observability](/trilha/reference/observability): Config.Observability, health endpoints, metrics registry, environment variables and the contract of each response.
- [auth](/trilha/reference/auth): Provider, Options, Auth, User and Store — the API of the auth package, with the defaults and what each field changes.
- [cache](/trilha/reference/cache): Options, Key, Cache, Do, Get and Once — the API of the cache package, with the defaults and what each field changes.
- [ui](/trilha/reference/ui): The kit's components, variants, assets and the theme contract.
- [ai](/trilha/reference/ai): OpenAI-compatible client, tools, agents, handoffs and composition.
- [mcp](/trilha/reference/mcp): Model Context Protocol client and server (stdio and Streamable HTTP).
- [CLI](/trilha/reference/cli): The trilha commands and their options.
- [Performance and comparison](/trilha/reference/performance): How much Trilha costs over the standard library, how to measure it yourself, and how it compares with other approaches.

## Cookbook

- [Cookbook](/trilha/cookbook): The parts every app needs and no framework decides for you — database, session, upload, pagination, e-mail, scheduled task, Docker — with code that compiles.
- [Database](/trilha/cookbook/database): One pool for the process, queries that carry the request's context, a transaction that rolls back on its own, and migrations applied in order.
- [Sessions](/trilha/cookbook/sessions): Login with a signed cookie, the current user in a middleware, a flash message that survives one redirect — and nothing stored on the server.
- [Uploads](/trilha/cookbook/uploads): Receive a file with a ceiling, check what it really is, store it outside the served tree, and hand it back without letting it run.
- [Pagination](/trilha/cookbook/pagination): Page by offset while the list is short, by cursor when it is not, one extra row instead of a COUNT, and links a crawler can follow.
- [E-mail](/trilha/cookbook/email): One interface the handlers call, SMTP behind it in production, the log in dev, a body from a template, and headers that refuse to be injected.
- [Scheduled tasks](/trilha/cookbook/scheduled-tasks): A ticker that starts with the app and stops with it, one tick at a time, a panic that does not take the process down — and the line where cron becomes the right answer.
- [Docker](/trilha/cookbook/docker): A static binary in a distroless image, the assets already inside it, the variables it needs, and a health probe the orchestrator can use.
- [Production checklist](/trilha/cookbook/production-checklist): What to check before publishing, in order: what trilha audit finds for you, what it cannot see, and the two things to prepare for the day it goes wrong.
- [Migration](/trilha/cookbook/migration): From plain net/http to Trilha one route at a time, without a rewrite — and what to look at when you move between minor versions.