Move htmx pages to Inertia
Since v0.6.0
A project of the web stack renders its pages with templ and htmx. The react, svelte and vue stacks keep the same Go side (routes, handlers, sessions, validation, logins) and render the pages as components with Inertia. Moving from one to the other changes the views, not the app: the handlers send props instead of rendering templ components. This guide moves a project page by page, with both kinds of pages working side by side until the last one moves.
Before you start
- A project made with
anetos new(the web stack), with Anetos v0.6 or later, and Node.js 20.19 or 22.12 or later. - Commit your work first: you’ll copy files over the project’s own.
- The guide uses React; for Svelte or Vue, use
--stack=svelteor--stack=vue, and the files of that stack, where it says React’s.
Steps
1. Make a reference project
The files you need are the ones anetos new writes for the stack you
move to. In another folder, make a project of that stack with your
project’s name and module path (go.mod’s first line), and run the
same generators your project ran:
cd /tmp
anetos new blog --stack=react --module=example.com/blog
cd blog
go tool anetos make:auth # if your project has accounts
go tool anetos make:crud Post title:string body:text published:bool # each make:crud you ranThis reference project is what you copy from. Diffing it with your project shows what each step changes.
2. Add the frontend
In your project:
go tool anetos vite:installIt adds frontend/ with Vite, vite.New in main.go, the /build/
route, a Node stage in the Dockerfile and the build in .gitignore and
.dockerignore, and installs the packages. Its frontend is a plain
script for the templ pages; replace it with the reference project’s:
- Remove the line
@vite.Tags("src/main.ts")it added toviews/layout.templ(and theviteimport, if nothing else uses it), andfrontend/src/main.tsandmain.css. - Copy from the reference project:
frontend/package.json,package-lock.json,vite.config.tsandtsconfig.json;frontend/src/withoutpages/andcomponents/SocialButtons.tsx(the accounts’ pages’ parts: step 6), thenpages/Error.tsx;views/app.templ, the root view;app/handlers/pages.go, which declares the pages and the props every page shares; andpublic/favicon.svg. - Add the keys of the reference project’s
locales/en/app.yamlthat yours lacks (errors.request_id). - Run
npm installinfrontend/.
With accounts, pages.go gets the logged-in user from authUser, in
the reference project’s app/handlers/auth.go. Until the accounts'
pages move (step 6), get it in pages.go itself (importing
anetos.dev/anetos/auth and your app/models):
// illustrative: app/handlers/pages.go, until the accounts move
func currentUser(c *web.Ctx) (*SharedUser, error) {
u, ok := auth.User[*models.User](c)
if !ok {
return nil, nil
}
return &SharedUser{ID: u.ID, Name: u.Name, Email: u.Email, EmailVerified: u.EmailVerifiedAt != nil}, nil
}3. Set Inertia up
In main.go’s setup, add Inertia, with the root view, the shared
props and the pages, after the vite.New that vite:install wrote,
which takes vite.WithReactRefresh() for React’s hot reload (Svelte and
Vue don’t take it):
// illustrative: main.go, in setup
if _, err := vite.New(app, public.Files, vite.WithReactRefresh()); err != nil {
return nil, err
}
in, err := inertia.New(app, views.App(), inertia.WithShared(handlers.SharedProps), inertia.WithPages(handlers.Pages...))
if err != nil {
return nil, err
}main.go imports anetos.dev/anetos/web/inertia,
anetos.dev/anetos/web/typescript, and your app/handlers and views
packages. After the routes (before ext.Load(plugins())), the
command that writes the
frontend’s types:
// illustrative: main.go, at the end of setup
if err := typescript.Register(app, srv, typescript.Config{Inertia: in, Routes: true, ExcludeRoutes: []string{"admin."}}); err != nil {
return nil, err
}In routes/web.go, and in routes/auth.go with accounts, the pages'
groups get Inertia’s middleware, and CSRF protection gives Inertia’s
client its token in a cookie:
// illustrative: routes/web.go
pages := r.Group("", sessions.Middleware, web.CSRF(web.WithXSRFCookie()), inertia.Middleware)Both files import anetos.dev/anetos/web/inertia. The error pages
become the frontend’s Error page, for the templ pages too (then
routes/web.go no longer uses view and views: remove their
imports):
// illustrative: routes/web.go
r.ErrorPages(inertia.ErrorPages("Error"))Then go tool templ generate, go run . types, and
go tool anetos dev: the templ pages work as before.
4. Move a page
Take one page, the posts’ list, say. In Go, the handler renders a page with props instead of a templ component:
// illustrative: before, in app/handlers/posts.go
return web.Render(views.PostsPage(page)), nil
// after
return postIndexPage.Responder(PostsIndexProps{Page: db.MapPage(page, postItem)}), nilwith the page and its props declared beside it
(postIndexPage = page[PostsIndexProps]("Posts/Index")). For pages a
generator wrote, the reference project has the code, a file for a
model’s pages: make:crud’s list, page and form move together. Copy
the handlers’ file, the components (frontend/src/pages/Posts/) and
the test, which checks the component and the props; delete the templ
file (views/posts.templ); run go tool templ generate and
go run . types. Then make your own changes to those pages again, in
the components and their text in locales/ (a column you added, a
cell the list shows differently). For a page of your own, see Build
pages in React. The home page (app/handlers/home.go,
views/home.templ) moves the same way, with the reference project’s
frontend/src/pages/Home.tsx, main_test.go and home.edit text in
locales/en/app.yaml.
The two kinds of pages link to each other as they are. A link in a
component to a page not moved yet works: Inertia’s middleware answers
the client’s visit to a templ page with 409 and its address, and the
client loads it whole (the browser’s console notes the 409). A link in
a templ page to a moved one loads it whole too. A message flashed
before the redirect shows on either kind. Two kinds of links aren’t
covered: to a route outside the pages’ groups (the admin’s), and with
Inertia’s prefetch; make those plain <a> links.
5. Move the others
One by one, with the app working after each. The text stays in
locales/, which the components read with useT(). The tests check
props rather than HTML (AssertInertia, AssertInertiaProp). Once
app/handlers/pages.go and frontend/package.json are in, the tool
takes the project for a react one: make:crud writes React pages and
adds its link to frontend/src/Layout.tsx (add one to
views/layout.templ by hand while templ pages remain), and
go tool anetos agent:update updates the coding agents’ files.
6. Move the accounts’ pages together
make:auth’s pages share handlers, so they move at once: copy the
reference project’s app/handlers/auth.go and settings.go,
routes/auth.go, auth_test.go, frontend/src/pages/Auth/ and
frontend/src/components/SocialButtons.tsx, then put back the
reference project’s currentUser in pages.go, which returns
authUser(c) (the copied auth.go has it). If you
changed make:auth’s handlers, make the same changes in the copies.
7. Remove what’s left of templ’s pages
When no page renders a templ view (the home page included):
- Delete
views/butapp.templandauth_mail.templ(the emails stay templ),views/ui/, andpublic/static/. - Take the reference project’s
public/public.go(noAssets) androutes/web.go’s first lines: noweb.MethodOverride(Inertia sends PUT and DELETE as they are) and no/assets/route. Keep your routes. - Run
go tool anetos agent:update, thengo tool anetos check.
Complete example
A project of the web stack with make:auth and make:crud, moved this
way, ends with the reference project’s code, but for comments, the
order of setup’s lines, the README (which still describes the web
stack: take the reference project’s) and the text you changed.
How it works
The handlers, routes, sessions and validation are the same in both
stacks: what differs is how a page is written. A templ page is HTML
from the server; an Inertia page is a component’s name and its props,
which the client renders. On a first visit, the root view
(views/app.templ) holds the page; after that, links and forms are
requests the server answers with the next page’s props as JSON.
When such a request reaches a handler in the group that writes
ordinary HTML (a templ page), inertia.Middleware doesn’t send that HTML
to the client, which would show it in an error dialog: it answers
409 with X-Inertia-Location, and the client loads the page whole.
The handler runs twice for that link: once for the client’s request,
then for the page load.
Testing it
After each page: go test ./... and a look in the browser. The
reference project’s tests show how a page’s test reads:
// illustrative
app.Get("/posts").AssertOK().AssertInertia("Posts/Index").AssertInertiaProp("page.total", 0)go tool anetos check runs the tests and the frontend’s build, which
type-checks every component.
Common problems
| Problem | Cause | Fix |
|---|---|---|
vite: "src/main.ts" isn't an entry of build/manifest.json on the templ pages | vite:install’s line is still in views/layout.templ | Remove @vite.Tags("src/main.ts") (step 2) |
| The type check fails on the reference project’s pages | Components were copied for pages your project doesn’t have yet | Copy a page’s components when you move it |
undefined: authUser | pages.go came from a project with accounts, before the accounts’ handlers | Use step 2’s currentUser until step 6 |
| A key shows instead of its text | The components read keys the templ pages didn’t use | Copy the reference project’s keys into locales/ |
| A form posts but nothing happens | The group lacks inertia.Middleware, or CSRF lacks web.WithXSRFCookie() | Step 3, for each pages’ group |
Next steps
- Build pages in React, in Svelte, in Vue.
- Pages in Vue, React or Svelte with Inertia: the protocol.
- Move htmx pages to an API and an SPA: the other way.
- Frontends.