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

Frontends

Since v0.6.0

Anetos serves a frontend three ways: pages rendered on the server with templ and htmx; pages written as React, Svelte or Vue components that Inertia renders, with the Go side unchanged; and a JSON API with a frontend of its own, a single-page app or a mobile app. This page is how each works, what each keeps in Go, and how to choose.

Three ways

Server-rendered pages (anetos new, the web stack). A handler renders a templ component, which is Go: the compiler checks its parameters, and it escapes what it prints. htmx swaps parts of a page without a reload. Forms post, and an invalid one is redirected back with its errors and what was typed, through the session. Node isn’t needed; vite:install adds a frontend for the pages’ scripts and styles when you want one. See Server-rendered HTML.

Pages as components (anetos new --stack=react, svelte or vue). The routes, handlers, sessions, validation and redirects are the web stack’s; a handler renders a page by naming its component and giving its props, a Go struct. On the first visit the HTML holds the page; Inertia’s client renders it, then turns links and form posts into requests the server answers with the next page’s props, as JSON. The props’ and routes’ TypeScript types are generated from the Go code. See Build pages in React, in Svelte, in Vue, and Inertia.

An API and a frontend of its own (anetos new --stack=api). The handlers return typed results as JSON, described by an OpenAPI document; a typed TypeScript client is generated from the same types. The frontend is an app of its own: an SPA the binary serves at its address (vite:install), or one in another repository or on a CDN, or a framework with its own server, or a mobile app. A first-party SPA on the same site logs in with the session cookie; other clients use tokens. See Build a single-page app and Build an API.

What each keeps in Go

Server-rendered pagesPages as componentsAn API and a frontend
Routes and URLsGoGoGo for the API; the frontend’s router for its pages
Rendering the HTMLThe server (templ)The browser (the component)The browser, or the frontend’s server
Data for a pageThe handler passes it to the viewThe handler’s propsThe frontend asks the API
Validation errorsRedirected back, in the sessionRedirected back, in the errors propA 422 answer, by field
LoginSession cookieSession cookieSession cookie for a first-party SPA; tokens for other clients
CSRFA token in forms and htmx’s headerThe XSRF-TOKEN cookieThe XSRF-TOKEN cookie for the SPA; none needed with tokens
Types shared with the frontendNot needed: templ is GoProps and routes, generatedThe client, generated
NodeNot neededTo buildTo build the SPA (or the frontend’s own)
make:auth, make:crudtempl pagesThe stack’s componentsJSON endpoints
Other clients (mobile apps, programs)Add an APIAdd an APIThe same API

The app is one binary: the templ views are compiled in, and a frontend Vite builds is embedded in it, unless the frontend is served elsewhere (another repository, a CDN, a framework’s own server).

Choosing

  • Mostly forms, lists and records, or a team at home in Go and HTML: server-rendered pages. Fewest moving parts, no build step for the frontend, and links and forms that work without JavaScript, which htmx improves where you add it.
  • Pages with much client-side interaction (editors, dashboards, drag and drop), or a team that knows React, Svelte or Vue: pages as components. The routes, logins and validation stay in Go, with no API to design or version.
  • Several clients (an SPA and a mobile app, or other people’s programs), or a frontend built and deployed by another team: an API. The API is a contract of its own, described by its OpenAPI document.

The choice isn’t final. A web project can move its pages to components one at a time (Move htmx pages to Inertia): both kinds of pages work in one app during the move. Moving to an API changes every page and most handlers (Move htmx pages to an API and an SPA).

Guarantees and trade-offs

  • Pages as components are rendered in the browser. The first visit’s HTML holds the page’s data, not its markup: search engines that run scripts index it; those that don’t see an empty page. Server-side rendering isn’t supported yet. Server-rendered pages don’t have this trade-off.
  • Node is a build tool, not a runtime. The frontend is built before the binary (anetos build); the server needs neither Node nor node_modules.
  • The types follow the Go code. Renaming a prop, a field of an API’s result or a route changes the generated TypeScript, and the frontend’s type check (in anetos check and anetos build) fails where it’s used. In development, Vite serves the change without a type check: run check before calling a change done.
  • A first-party SPA’s cookie needs one site. The SPA and the API must be on the same site (one domain, or subdomains of one) for the session cookie; elsewhere, the SPA logs in with a token (Protect your app in the browser).
  • An API project scaffolds one SPA’s plumbing, not its pages. vite:install writes a plain TypeScript SPA; examples/spa has one in React with the accounts’ pages.

Related