Skip to content
Unreleased: these pages follow the main branch. The latest release is v0.5.
Pages in Vue, React or Svelte with Inertia

Pages in Vue, React or Svelte with Inertia

Since v0.6.0

Write the pages as Vue, React or Svelte components while the routes, handlers, sessions, validation and redirects stay in Go. A handler renders a page component with its props, which Inertia’s client shows; links and forms then visit the server without reloading the page. There is no JSON API to design: the props are the page’s data.

Package web/inertia is the server side of Inertia’s protocol (v3). The client is Inertia’s own: @inertiajs/react, @inertiajs/vue3 or @inertiajs/svelte. A new project can have it set up from the start; the steps below set it up by hand in a web project, with React. The Go side is the same for the three.

Start a project with it

anetos new shop --stack=react   # or --stack=vue, --stack=svelte
cd shop
go tool anetos dev

The react, vue and svelte stacks are the web stack’s Go side (routes, handlers, sessions, CSRF protection, validation, translations) with pages that are React, Vue or Svelte components in TypeScript, styled by the starter theme. In the react stack:

  • app/handlers/pages.go declares the pages, page[P](component), and the props every page gets (Shared): the app’s name, the locale, the flashed message (notice), the logged-in user and the page text.
  • frontend/src/pages/ holds the components, Home.tsx and Error.tsx at first, made of the components in src/components/ui.tsx (PageHeader, Card, Field, Input, Button, Table…) inside src/Layout.tsx, the header, nav and footer.
  • The text comes from locales/, with the web stack’s keys: useT() from src/i18n.ts translates with the catalogs the server sends once per locale (i18n.Messages), placeholders and plurals included, and useFormat() writes numbers and dates the locale’s way.
  • Links name their routes: route('posts.show', { id: post.id }) from src/types/routes.ts, which go run . types writes with the pages' props (src/types/pages.ts). Renaming a route, or leaving out a parameter, fails the type check that go tool anetos build runs.

The vue stack has the same with .vue files: src/Layout.vue, the components in src/components/ui/, src/pages/Home.vue. A page takes its own props with their type from pages.ts, and the shared ones from usePage():

<!-- illustrative: frontend/src/pages/Posts/Index.vue -->
<script setup lang="ts">
import { usePage } from '@inertiajs/vue3'
import type { PostsIndexProps } from '../../types/pages'

defineProps<PostsIndexProps>() // posts, in the template
const shared = usePage() // shared.props.user, read where it's used
</script>

Its build type-checks the templates too, with vue-tsc on TypeScript 6 (vue-tsc needs TypeScript’s JavaScript API, which TypeScript 7 doesn’t have).

The svelte stack has .svelte files (Svelte 5, with runes): a page takes its props with their type (let { page }: PostsIndexProps = $props()), its title with <Title text={…} /> (from src/components/ui), and builds its links with route() from src/routes.ts, which reads the locale’s prefix from the page, so a link follows a change of locale. svelte-check, on TypeScript 6 too, type-checks the components in the build.

go tool anetos make:auth and make:crud write the stack’s pages too, rendered by the same handlers as the web stack’s, and update the types:

go tool anetos make:auth
go tool anetos make:crud Post title:string body:text published:bool
go run . migrate

The CLI reference lists the files, and Build pages in React, in Svelte and in Vue add a page step by step. The rest of this guide is how the parts work, and how to add Inertia to a project made without it; a web project’s templ pages can move to it one at a time (Move htmx pages to Inertia).

Before you start

Steps

1. Install the client

In frontend/:

npm install @inertiajs/react react react-dom
npm install -D @vitejs/plugin-react @types/react @types/react-dom

Add React’s plugin to vite.config.ts (plugins: [react()]), and "jsx": "react-jsx" to tsconfig.json’s compilerOptions. Make the entry src/app.tsx, which starts Inertia’s client and finds each page in src/pages:

// illustrative: frontend/src/app.tsx
import { createInertiaApp } from '@inertiajs/react'
import { createRoot } from 'react-dom/client'
import type { ComponentType } from 'react'

const pages = import.meta.glob<{ default: ComponentType }>('./pages/**/*.tsx')

createInertiaApp({
  resolve: (name) => {
    const page = pages[`./pages/${name}.tsx`]
    if (!page) throw new Error(`no page ${name}`)
    return page().then((m) => m.default)
  },
  setup({ el, App, props }) {
    if (el) createRoot(el).render(<App {...props} />)
  },
})

List it in vite.config.ts’s inputs (input: ['src/app.tsx']). The page Notes/Index is then src/pages/Notes/Index.tsx.

2. Write the root view

The root view is the HTML of a first visit: it loads the frontend and holds the page for the client. @inertia.App() writes the page object and the element the client renders in:

// root is the root view: the HTML of a first visit, which loads the
// frontend and holds the page for Inertia's client.
templ root() {
	<!DOCTYPE html>
	<html lang="en">
		<head>
			<meta charset="utf-8"/>
			<meta name="viewport" content="width=device-width, initial-scale=1"/>
			<title>Notes</title>
			@vite.Tags("src/app.tsx")
		</head>
		<body>
			@inertia.App()
		</body>
	</html>
}

(Copied from examples/inertia/app.templ, region root.)

3. Set it up

In main.go’s setup, inertia.New takes the root view. Its options add shared props, which every page gets (the app’s name, the logged-in user), and list the pages, whose props get TypeScript types (typescript.Register adds the command that writes them: see Generate TypeScript types for the frontend). In the routes, inertia.Middleware runs after the session and CSRF middleware; web.WithXSRFCookie gives Inertia’s client the CSRF token in the cookie it reads. inertia.ErrorPages makes the error pages the frontend’s Error component:

func setup(app *anetos.App) (*web.Server, error) {
	srv, err := web.NewServer(app)
	if err != nil {
		return nil, err
	}
	sessions, err := session.New(app)
	if err != nil {
		return nil, err
	}
	if _, err := vite.New(app, public.Files, vite.WithReactRefresh()); err != nil {
		return nil, err
	}
	shared := func(*web.Ctx) (Shared, error) { return Shared{AppName: app.Config().Name}, nil }
	in, err := inertia.New(app, root(), inertia.WithShared(shared), inertia.WithPages(notesIndex, notesCreate))
	if err != nil {
		return nil, err
	}

	r := srv.Router()
	r.ErrorPages(inertia.ErrorPages("Error"))
	r.Get("/build/{path...}", web.WrapHandler(vite.Handler()))
	h := notes{store: newStore()}
	g := r.Group("", sessions.Middleware, web.CSRF(web.WithXSRFCookie()), inertia.Middleware)
	g.Get("/", func(c *web.Ctx) error { return c.RedirectRoute("notes.index") })
	g.Get("/notes", h.index).Name("notes.index")
	g.Get("/notes/new", h.create).Name("notes.create")
	g.Post("/notes", web.H(h.save))
	g.Delete("/notes/{id}", h.delete)
	g.Get("/boom", func(*web.Ctx) error { return web.Error(http.StatusTeapot, "This page is a teapot.") })

	// go run . types writes the pages' props as TypeScript, in
	// frontend/src/types (anetos dev does after each build).
	if err := typescript.Register(app, srv, types(in)); err != nil {
		return nil, err
	}
	return srv, nil
}

// types is where the frontend's TypeScript types come from.
func types(in *inertia.Inertia) typescript.Config {
	return typescript.Config{Inertia: in}
}

(Copied from examples/inertia, region setup.)

vite.WithReactRefresh() adds what React’s hot reload needs in development; leave it out for Vue and Svelte.

4. Declare the pages

A page is declared once, at package level, with the Go type of its props. Its fields are the props, as encoding/json writes them (their json tags, omitempty, embedded structs):

// NotesIndex are the props of the list: a page of notes, which the
// client appends to the ones it shows when it loads more, and the
// statistics, which it asks for after the page shows.
type NotesIndex struct {
	Notes inertia.Prop[[]Note] `json:"notes"`
	Next  int                  `json:"next"` // the next page, 0 after the last
	Stats inertia.Prop[Stats]  `json:"stats"`
}

// Stats are the list's statistics, slow to compute.
type Stats struct {
	Count int `json:"count"`
	Words int `json:"words"`
}

// NotesCreate are the props of the form.
type NotesCreate struct {
	MaxTitle int `json:"maxTitle"`
}

var (
	notesIndex  = inertia.NewPage[NotesIndex]("Notes/Index")
	notesCreate = inertia.NewPage[NotesCreate]("Notes/Create")
)

(Copied from examples/inertia, region pages.)

The props’ types are the page’s contract with the frontend. NewPage reads them once, when the program starts, and panics on a mistake: two props of one name, or a prop named errors, which holds the validation errors.

5. Render them

A handler renders the page with its props:

func (h notes) index(c *web.Ctx) error {
	p, _ := strconv.Atoi(c.Query("page"))
	list, next := h.store.page(max(p, 1), 10)
	return notesIndex.Render(c, NotesIndex{
		Notes: inertia.Merge(list).MatchOn("id"),
		Next:  next,
		Stats: inertia.Defer(func(ctx context.Context) (Stats, error) {
			time.Sleep(300 * time.Millisecond) // a slow query
			return h.store.stats(), nil
		}),
	})
}

func (h notes) create(c *web.Ctx) error {
	return notesCreate.Render(c, NotesCreate{MaxTitle: 60})
}

// save saves a note; an invalid one is sent back to the form with its
// errors, which the page gets in its errors prop.
func (h notes) save(c *web.Ctx, in NoteInput) (web.Responder, error) {
	n := h.store.add(in)
	inertia.Flash(c, "toast", "Saved “"+n.Title+"”.")
	return web.RedirectRoute("notes.index"), nil
}

(Copied from examples/inertia, region handlers.)

The component gets the props, typed from the Go types (frontend/src/types/pages.ts, which go run . types writes):

// illustrative: frontend/src/pages/Notes/Index.tsx
import type { PageProps } from '../../types/pages'

export default function Index({ notes = [], next, stats }: PageProps<'Notes/Index'>) {
  // …
}

A failed post is sent back to the page it came from, as with templ pages, and the page gets the field errors in its errors prop ({"title": "The title field is required."}). Inertia’s <Form> and useForm show them:

// illustrative: frontend/src/pages/Notes/Create.tsx
<Form action="/notes" method="post">
  {({ errors }) => (
    <>
      <input name="title" />
      {errors.title && <p>{errors.title}</p>}
      <button type="submit">Save</button>
    </>
  )}
</Form>

A form that names an error bag (errorBag: 'createNote') gets them under it (errors.createNote.title).

6. Choose how each prop loads

A plain field is sent with every visit of the page. An inertia.Prop[T] field loads as you say:

Set it toThe prop
inertia.Func(fn)Is computed by fn only when the response includes it: a partial reload that leaves it out doesn’t run fn
inertia.Defer(fn)Is left out of the visit and loaded by the client right after the page shows, so a slow query doesn’t hold the page. .Group("charts") loads the props of a group together; .Rescue() leaves a failed one out instead of failing the response
inertia.Optional(fn)Loads only when the client asks for it (router.reload({ only: ['users'] }))
inertia.Merge(v)Is appended to the value the page holds on a partial reload: “load more”. .Append("data") and .Prepend(…) merge arrays inside it; .MatchOn("id") replaces the items with the same id instead of adding them again; .DeepMerge() merges at every depth instead of appending
inertia.Once(fn)Is loaded once and kept by the client across pages, until it expires (.ExpiresIn(time.Hour))
inertia.Always(v)Is sent even when a partial reload asks for other props

Their methods combine: inertia.Defer(fn).Append() is a deferred list that grows. A Prop field you don’t set is left out of the page.

7. Messages, redirects and history

  • inertia.Flash(c, "toast", "Saved.") gives the next page Inertia renders, here or after a redirect, data in page.flash (usePage().flash in React). It, ClearHistory and EncryptHistory need inertia.Middleware on the route.
  • c.Redirect and c.RedirectRoute work as usual; the middleware turns a 302 after PUT, PATCH or DELETE into a 303, so the browser follows it with a GET.
  • inertia.Location(c, url) sends the browser to another site, or to a page that isn’t Inertia’s (a download), with a full page load.
  • inertia.ClearHistory(c) at logout makes the pages kept in the browser’s history unreadable, with history encryption (inertia.WithEncryptHistory(), HTTPS only).

Complete example

examples/inertia is a notes app in React: a list that loads more notes and its statistics after the page shows, a form with errors from the server, a message after saving, deleting, and the error page. Its tests run without Node; its frontend runs with go tool anetos dev.

How it works

The first visit is an ordinary GET: the handler’s Render answers with the root view, whose <script data-page="app" type="application/json"> holds the page object (the component, the props, the URL and the asset version). The client renders it, then takes over the links and forms: each later visit is a request with X-Inertia: true, answered with the page object as JSON, and the client swaps the component in place.

  • Partial reloads ask for some props (X-Inertia-Partial-Data); the others aren’t computed when they are Func, Defer or Optional props.
  • Asset versions: the page carries the frontend build’s version (a hash of Vite’s manifest). After a deploy, a client with the old one gets a 409, and loads the page whole with the new scripts; flashed messages and errors are kept for that load.
  • Pages that aren’t Inertia’s: a link in a component to a templ page in the group gets an ordinary HTML page, which the client would show in its error dialog. inertia.Middleware answers such a visit with 409 and X-Inertia-Location instead, keeping what was flashed, and the client loads the page whole; the handler runs twice for that link. Routes outside the group (the admin’s) and prefetching links (prefetch) aren’t covered: link to those pages with a plain <a>.
  • CSRF: the XSRF-TOKEN cookie holds the session’s token, which the client sends back in X-XSRF-TOKEN. web.CSRF checks it as it checks a form’s _token.
  • Errors: a 404, a 403 or a 500 is the Error component with status, title, detail and requestId, in the page, instead of the client’s error dialog. In debug mode (APP_DEBUG), a 500 is still the debug page, which the client shows in its dialog.

Server-side rendering, infinite scroll and Precognition (validating as the visitor types) aren’t supported yet.

Coming from another framework? This is the Inertia protocol that the adapters of other frameworks implement (Django, Laravel, Rails). The props are a Go struct per page rather than a dictionary, so the frontend’s TypeScript types can come from it.

Testing it

The tests need neither Node nor a build. app.AsInertia() makes the requests the client’s; AssertInertia and AssertInertiaProp check the page, and InertiaPage() returns the whole page object:

func TestNotes(t *testing.T) {
	app := anetostest.New(t, setup)

	// The first visit: the root view's HTML holding the page.
	app.Get("/notes").AssertOK().AssertInertia("Notes/Index").AssertInertiaProp("next", 2)

	// The client's visits after it get the page object.
	app.AsInertia()
	page := app.Get("/notes").AssertOK().InertiaPage()
	if page.DeferredProps["default"][0] != "stats" || page.MergeProps[0] != "notes" {
		t.Errorf("deferred %v, merged %v", page.DeferredProps, page.MergeProps)
	}

	// An invalid note goes back to the form with its errors.
	app.Get("/notes/new").AssertInertia("Notes/Create")
	app.PostJSON("/notes", NoteInput{Title: ""}).AssertRedirect("/notes/new")
	app.Get("/notes/new").AssertInertiaProp("errors", map[string]string{"title": "The title field is required."})

	// A valid one is saved, with a message for the next page.
	app.PostJSON("/notes", NoteInput{Title: "Groceries"}).AssertRedirect("/notes")
	page = app.Get("/notes").InertiaPage()
	if string(page.Flash["toast"]) != `"Saved “Groceries”."` {
		t.Errorf("flash %s", page.Flash["toast"])
	}
}

(Copied from examples/inertia/main_test.go, region test.)

Common problems

SymptomCauseFix
A post answers 403 “The page has expired”The client has no XSRF-TOKEN cookieAdd web.WithXSRFCookie() to web.CSRF in the pages’ group
inertia: no Inertia in the contextinertia.New wasn’t called in setupCall it in setup
The client shows a dialog with an HTML pageThe response isn’t Inertia’s: a route outside the group with inertia.Middleware, or an error without inertia.ErrorPagesPut the page’s route in the group, and set the error pages
Every visit reloads the whole pageThe asset version changes on each request, or the client sends another oneLeave the version to Vite’s build (the default), or give inertia.WithVersion a value that changes only with the assets
inertia: NewPage("…"): … the prop name errors is Inertia'sA prop named errorsRename it: the page gets the validation errors there
A shared prop has another value on one page (the layout’s text, <html lang>)A prop of the page has its name: the page’s props take the place of the shared ones, without a warningRename one of them (the stacks’ shared flash message is notice, not status, which the error page has). The generated pages’ props: page, item (make:crud’s); status, title, detail, requestId (Error); social, token, tokens, newToken, oldEmail, newEmail, on, started, secret, qr, recoveryCodes, recoveryCodesLeft, and the settings page’s name, email, emailVerified, emailUrl, pendingEmail, hasPassword, locales, timeZones, localePreference, timeZonePreference, twoFactor, twoFactorOn, deleteUrl (make:auth’s)

Next steps