Reference

File conventions

Complete table of what each file and folder name in app/ means.

Files#

page.go and route.go in the same folder is an error. The function may live in any file of the package; the file name is what binds the convention.

Kind follows the subtree#

Kind is a variable, not a function, and it is inherited like Layout and Middleware: declared in the package of a folder, it decides that folder and everything below it, and the deepest declaration wins. kind.go is the file name for a folder that has no route.go of its own — a subtree root has to be able to speak without owning a route:

// app/painel/kind.go — this branch is browser pages, so its writes enforce CSRF
package painel

var Kind = trilha.KindPage

This matters more than error rendering: Kind is what turns CSRF on. A route.go is an API by default, and an API does not check the token, so the same form action moved from a page.go into a route.go starts accepting a POST from another site — silently. One line at the root of the branch covers every leaf, including the leaf someone adds next month. trilha audit reports a write route that no Kind reaches in an app that also serves pages.

A page.go route is a page whatever the branch above it says: an inherited KindAPI never turns a page into JSON.

The variable is a trilha.RouteKind, and its three values are trilha.KindAuto, trilha.KindPage and trilha.KindAPI. KindAuto is the zero value and what almost every route has: the kind comes from the file — page.go is a page, route.go is an API — which is why declaring anything is the exception and not the ritual. Route.Kind answers the value after the inheritance, so a test can assert the branch it was worried about.

Folders#

A folder with a dot in its name serves a fixed path with an extension. Since app.css is not a Go identifier, declare another package name in the file (package appcss); the generator imports everything with an alias, so the package name does not matter.

Folders that start with a dot stay ignored, with a single exception: .well-known, where RFC 8414, RFC 9728, RFC 8555, RFC 9116 and OpenID Discovery publish their documents. Inside it the conventions are the usual ones — app/.well-known/security.txt/route.go answers /.well-known/security.txt. A page.go or route.go inside any other dot folder is now an E_HIDDEN_ROUTE error instead of a 404 nobody can explain; to park a folder out of the routing on purpose, start its name with _.

The Go tool does not match a path with a dot in ./..., so go vet ./... and go test ./... skip that package as a target. It still compiles: trilha_gen.go imports it by its explicit path.

Cross-origin on one route#

Config.CORS is the policy of the whole app. When only a few paths are public — the discovery documents under /.well-known/, fetched from another origin by a client that has no session yet — the route carries its own:

package oauthresource

// Only this route. The other routes stay same-origin.
var CORS = trilha.CORS{Origins: []string{"*"}, Methods: []string{"GET"}}

func GET(c *trilha.Ctx) error { ... }

The framework answers the preflight from the policy (204 with Access-Control-Allow-*, or 403 for an origin or method that is not on the list) and adds the headers to every response of that route. A route that declares its own policy decides alone: the app-wide list neither widens nor narrows it. Writing func OPTIONS in the same file takes the preflight back — the common case is declarative, the odd one is still yours.

HEAD is not a handler name: since Go 1.22 the router answers HEAD with the GET handler.

Precedence: segment by segment, left to right — a literal beats a parameter, which beats a catch-all, at the first position where the two patterns differ. A tie on every comparable position goes to the pattern with more segments, the one that spells more of the URL out. So /o/{slug}/login answers /o/cards/login and /{lang}/cards/{deckId} answers /en/cards/deck-1, and registering the two is fine — http.ServeMux refuses that pair, because by its rule neither is more specific, and Trilha dispatches the handful of patterns it turns down itself. Two sibling dynamic folders are an error. Two folders producing the same URL (through groups) are an error.

A file in public/ (or in a Mounts tree) answers before a route with a wildcard in it and after a route spelled out in full. An app with app/lang_ (that is, /{lang}) at the root still serves /ui.css from the file; an app with app/manifest.webmanifest/route.go keeps answering that address from the route, and c.Asset("/manifest.webmanifest") says so in the log, once.

Other project folders#

Execution order for GET /a/b#

middleware(app) → middleware(app/a) → middleware(app/a/b)
  → middlewareGET(app) → middlewareGET(app/a) → middlewareGET(app/a/b)
  → Page (or method)
  → layout(app/a/b) → layout(app/a) → layout(app)

The per-method chain runs inside the route-wide one: a rule for a single method refines what the route already decided. For POST it is MiddlewarePOST, and so on; a method with no chain of its own just runs the route's.

A page that works offline#

var Offline = true in the package of a page.go says this screen is one a service worker keeps a copy of. It is the page's own flag and is not inherited down the subtree, because what opens with no network is decided screen by screen:

// app/coleta/offline.go
package coleta

var Offline = true

The framework serves the route exactly as before; the flag is a fact the app publishes. App.OfflineRoutes() answers the declared patterns, sorted, and ui.OfflineScript hands them to the worker of trilha add pwa-offline — a route nobody declared is never cached. var Offline in a route.go is an error: a JSON answer is not a navigation.

Generation errors#