Skip to content
Unreleased: these pages follow the main branch. The latest release is v0.5.

Project structure

A project is a Go module. Its folders follow what each part of the app does; the generators (make:crud, make:auth…) add their files in the same places.

blog/
├── main.go               setup: the database, cache, queue, mail, server, routes…
├── main_test.go          tests of the home page and the 404 page
├── plugins.go            the plugins (anetos add)
├── app/
│   ├── handlers/         HTTP handlers: a request in, a page or JSON out
│   └── models/           models: Go structs for tables, and their typed columns
├── database/
│   ├── migrations/       changes to the tables, in Go, in order
│   └── factories/        test data
├── routes/
│   └── web.go            URLs to handlers, with their middleware
├── views/
│   ├── layout.templ      the page shell: the header, the flash message
│   ├── home.templ        the home page
│   ├── errors.templ      error pages (404, 500…) in the layout
│   └── ui/               the components the pages are made of: cards, forms, buttons, tables…
├── locales/en/app.yaml   the pages' text
├── public/               the web root: robots.txt, served at /robots.txt
│   └── static/           CSS (app.css, the starter theme), the icon (favicon.svg) and other files, at /assets/
├── deploy/               a systemd unit and the production settings
├── Dockerfile            a container image
├── .env                  settings for your machine (not in git)
├── .env.example          the settings, without secrets (in git)
├── AGENTS.md             instructions for coding agents (CLAUDE.md and GEMINI.md import it)
└── .agents/, .claude/    skills: coding agents' guides to common tasks

An API project (anetos new --stack=api) has routes/api.go instead of routes/web.go, app/handlers/welcome.go (the answer to GET /api/v1) instead of the home page, and no views/ or public/; locales/en/app.yaml holds its messages, and main_test.go tests the welcome and a 404’s JSON.

A react, svelte or vue project (--stack=react…) has the web project’s Go side, and its pages in frontend/: src/pages/ (Home, Error), src/Layout, src/components/ui, src/i18n.ts and src/types/ (written by go run . types). Instead of views/layout.templ, home.templ, errors.templ and ui/, views/ has app.templ, the root view; app/handlers/pages.go declares the pages and the props every page shares, and public/ has favicon.svg and the build in public/build. See Build pages in React, in Svelte or in Vue.

A web project made with --vite (or go tool anetos vite:install) also has frontend/: the scripts and styles Vite builds into public/build, which the layout loads with @vite.Tags. See Bundle JavaScript and CSS with Vite. In an API project, frontend/ is a single-page app, which Vite builds into public/spa and the app serves at /: see Build a single-page app.

How a request flows

  1. routes/web.go matches the URL to a handler and runs the route’s middleware: sessions and CSRF protection for pages.
  2. The handler, in app/handlers, reads the request (typed input, validated) and the database (the models of app/models).
  3. It renders a view of views/, inside Layout, or answers JSON. The views call the components of views/ui, which hold the markup and the class names (Style your app).

HTTP request lifecycle explains each step.

Settings

Settings come from the environment, and in development from .env: APP_KEY (made fresh for each project), DB_*, MAIL_* and the rest. Tests read .env.testing instead (or nothing, for SQLite: an in-memory database). The configuration reference lists every key.

Generated files

*_templ.go (from the .templ files) and app/models/models_gen.go (the models’ typed columns) are written by templ generate and anetos generate; anetos dev and anetos build run both. Commit them, but don’t edit them.

The CLI reference describes every file anetos new writes.

Next: Add pages for a model.