# Build pages in Vue

Source: https://docs.anetos.dev/main/guides/vue/

In a project of the vue stack, the Go side is the web stack's: routes,
handlers, sessions, validation, translations and logins stay in Go. The
pages are Vue single-file components in TypeScript, which Inertia's client renders
in the browser with the props a handler sends. Each page's props are a Go
struct, and the TypeScript types the components use are generated from
it, so the type check catches a renamed field or route before the
browser does.

This guide adds a page to a project with posts: a list of the drafts,
with a filter, a count in the header, and a test.

## Before you start

- Go 1.26 and Node.js 20.19 or 22.12 or later.
- A project of the vue stack with posts:

```sh
anetos new shop --stack=vue
cd shop
go tool anetos make:crud Post title:string body:text published:bool
go run . migrate
go tool anetos dev   # http://localhost:8080
```

`anetos dev` runs the app and Vite, rebuilds the app when Go code
changes, and updates the frontend's types (`go run . types`). Open the
app's address: Vite runs on a free port of its own, which the app's
pages load their scripts from.

## Steps

### 1. Know where things are

| File | Holds |
|---|---|
| `app/handlers/pages.go` | `page[P](component)`, which declares a page, and `Shared`, the props every page gets |
| `app/handlers/posts.go` | `make:crud`'s handlers, their pages and props |
| `routes/` | The routes: `web.go` has the `pages` group, `posts.go` the posts' routes |
| `frontend/src/pages/` | The components: `Home.vue`, `Posts/Index.vue`… A page named `Posts/Index` in Go is `pages/Posts/Index.vue` |
| `frontend/src/Layout.vue` | The header, nav and footer around every page; `components/NavLink.vue`, a link marked when it's the current page |
| `frontend/src/components/ui/` | The starter theme's components, a file each, all exported by `index.ts`: `PageHeader`, `Card`, `Field`, `Input`, `Button`, `Table`, `Pagination`… |
| `frontend/src/i18n.ts` | `useT()` for the text of `locales/`, `useFormat()` for numbers and dates |
| `frontend/src/types/` | Written by `go run . types`: `pages.ts` (the props), `routes.ts` (`route()`) |

### 2. Declare the page in Go

A page is its component's name and the Go type of its props. Add
`app/handlers/drafts.go`:

```go
// illustrative: app/handlers/drafts.go
package handlers

import (
	"anetos.dev/anetos/db"
	"anetos.dev/anetos/web"

	"shop/app/models"
)

// DraftsQuery is what the drafts page reads from the URL: ?q=, a part of
// the title.
type DraftsQuery struct {
	Q string `query:"q"`
}

// DraftsProps are the drafts page's props.
type DraftsProps struct {
	Q     string     `json:"q"`
	Posts []PostItem `json:"posts"`
}

var draftsPage = page[DraftsProps]("Posts/Drafts")

// Drafts lists the posts not published yet, newest first; with ?q=, those
// whose title contains it.
func (Posts) Drafts(c *web.Ctx, in DraftsQuery) (web.Responder, error) {
	q := db.Query[models.Post](c).Where(models.PostCols.Published.Eq(false)).
		OrderBy(models.PostCols.ID.Desc()).Limit(50)
	if in.Q != "" {
		q = q.Where(models.PostCols.Title.ContainsFold(in.Q))
	}
	rows, err := q.Get()
	if err != nil {
		return nil, err
	}
	posts := make([]PostItem, len(rows))
	for i, row := range rows {
		posts[i] = postItem(row)
	}
	return draftsPage.Responder(DraftsProps{Q: in.Q, Posts: posts}), nil
}
```

`PostItem` is `make:crud`'s: the fields of a post the pages get, so a
new column never shows by accident. Route it in `routes/posts.go`,
with a name:

```go
// illustrative: routes/posts.go
r.Get("/drafts", web.H(h.Drafts)).Name("posts.drafts")
```

`page` adds the page to `handlers.Pages`, which `setup` lists:
`go run . types` (which `anetos dev` runs) writes `DraftsProps` into
`frontend/src/types/pages.ts`, and `posts.drafts` into `routes.ts`.

### 3. Write the component

Add `frontend/src/pages/Posts/Drafts.vue`. It takes the props, with
their type from Go:

```vue
<!-- illustrative: frontend/src/pages/Posts/Drafts.vue -->
<script setup lang="ts">
// Posts/Drafts lists the posts not published yet, filtered by title.
import { Form, Head, Link } from '@inertiajs/vue3'
import { Button, Cluster, Empty, Input, PageHeader, Table } from '../../components/ui'
import { useT } from '../../i18n'
import type { DraftsProps } from '../../types/pages'
import { route } from '../../types/routes'

defineProps<DraftsProps>()
const t = useT()
</script>

<template>
  <Head :title="t('posts.drafts.title')" />
  <PageHeader :title="t('posts.drafts.title')" />
  <Form :action="route('posts.drafts')" method="get" :options="{ preserveState: true }">
    <Cluster>
      <Input name="q" :defaultValue="q" :aria-label="t('posts.drafts.search')" :placeholder="t('posts.drafts.search')" />
      <Button variant="secondary">{{ t('posts.drafts.filter') }}</Button>
    </Cluster>
  </Form>
  <Empty v-if="posts.length === 0" :text="t('posts.drafts.none')" />
  <Table v-else>
    <tbody>
      <tr v-for="post in posts" :key="post.id">
        <td>
          <Link :href="route('posts.show', { id: post.id })">{{ post.title }}</Link>
        </td>
      </tr>
    </tbody>
  </Table>
</template>
```

- **The filter** is Inertia's `<Form>` with `method="get"`: it visits
  `/drafts?q=…` without a page load, and `preserveState` keeps what was
  typed. The handler reads `q` from the URL (`DraftsQuery`), and
  `ContainsFold` matches it in any case on every database (`Contains`
  follows the database: PostgreSQL's is case-sensitive).
- **The path** is `/drafts`, not `/posts/drafts`: the layout's
  `NavLink` marks a link as the current page on the paths under it too,
  so under `/posts/` the Posts link would be marked as well.
- **Links** name their routes: `route('posts.show', { id: post.id })`.
  A route renamed in Go, or a parameter left out, fails the type check.
  `Link` visits the page without reloading the app.
- **The text** comes from `locales/`. Add the keys to
  `locales/en/posts.yaml`, under `posts:`:

```yaml
  drafts:
    title: "Drafts"
    search: "Title contains"
    filter: "Filter"
    none: "No drafts."
    nav: "Drafts ({count})"
```

Vue escapes what `{{ }}` prints, so a title holding `<script>` shows as
text. Don't write user data with `v-html`
([Protect your app in the browser](https://docs.anetos.dev/main/guides/browser-security/index.md#5-show-what-users-typed-as-text-xss)).

### 4. Share a prop with every page

The props of `Shared` in `app/handlers/pages.go` reach every page: the
app's name, the locale, the logged-in `user`, the flashed `notice`. Add
the number of drafts, for the header:

```go
// illustrative: app/handlers/pages.go, in Shared
	// Drafts is the number of posts not published yet.
	Drafts int64 `json:"drafts"`
```

```go
// illustrative: app/handlers/pages.go, in SharedProps, before the return
	drafts, err := db.Query[models.Post](c).Where(models.PostCols.Published.Eq(false)).Count()
	if err != nil {
		return Shared{}, err
	}
```

and `Drafts: drafts,` in the `Shared` it returns (`pages.go` then imports
`anetos.dev/anetos/db` and `shop/app/models`). That's a query on
every page: keep shared props cheap. A component reads them with
`usePage()`; in `frontend/src/Layout.vue`, which has
`const page = usePage()`:

```vue
<!-- illustrative: frontend/src/Layout.vue, in the nav -->
<NavLink route="posts.drafts" :label="t('posts.drafts.nav', { count: page.props.drafts })" />
```

The layout stays mounted as pages change; the count follows each visit.
A number in a message that isn't a plural one is written as given
(`{count}` in a plural message is formatted for the locale): pass
`useFormat().number(n)` for the locale's digits.

### 5. Take input with a form

`make:crud`'s `Posts/Form.vue` is the pattern for a form. Inertia's
`<Form>` posts to the route, and the handler's input struct validates
it before the handler runs (`validate:"required|max:255"`). An invalid
form comes back to the page with `errors`, by field, and what was typed
stays:

```vue
<!-- illustrative: from frontend/src/pages/Posts/Form.vue -->
<InertiaForm
  v-slot="{ errors, processing }"
  :action="item ? route('posts.update', { id: item.id }) : route('posts.create')"
  :method="item ? 'put' : 'post'"
  :transform="(data) => ({ ...data, published: data.published === '1' })"
>
  <Field name="title" :label="t('posts.fields.title')" :error="errors.title">
    <Input :defaultValue="item?.title" />
  </Field>
  <!-- … -->
  <Button :disabled="processing">{{ t('posts.save') }}</Button>
</InertiaForm>
```

The form's values are text, so `transform` turns them into what the
handler's input wants: `true` or `false` for the checkbox (and numbers
for number fields).

After saving, the handler flashes a message and redirects
(`c.Session().Flash("status", …)`, `web.RedirectRoute("posts.show",
row.ID)`); the layout shows it from the shared `notice`. The messages
of the rules are translated with the rest of the text
([Validation](https://docs.anetos.dev/main/guides/validation/index.md)).

### 6. Let only logged-in users in

`go tool anetos make:auth` adds registration, login, two-factor
authentication and the account's pages, in Vue, and fills the shared
`user` prop (`usePage().props.user`, null for a guest); then
`go run . migrate` creates the accounts' tables. To keep the posts for
logged-in users, move their routes into its `loggedIn` group: remove
`Posts(pages)` from `routes/web.go`, and in `routes/auth.go`:

```go
// illustrative: routes/auth.go, after loggedIn := …
Posts(loggedIn) // the posts, for logged-in users only
```

To let guests read the posts and only logged-in users change them,
split `routes/posts.go` in two, and call the second from
`routes/auth.go` with `loggedIn`:

```go
// illustrative: routes/posts.go
// Posts adds the pages anyone may see: routes/web.go calls it.
func Posts(r *web.Router) {
	var h handlers.Posts
	r.Get("/posts", web.H(h.Index)).Name("posts.index")
	r.Get("/drafts", web.H(h.Drafts)).Name("posts.drafts")
	r.Get("/posts/{id}", web.H(h.Show)).Name("posts.show")
}

// PostChanges adds the pages that change posts: routes/auth.go calls it
// with its loggedIn group.
func PostChanges(r *web.Router) {
	var h handlers.Posts
	r.Get("/posts/new", h.New).Name("posts.new")
	r.Post("/posts", web.H(h.Create)).Name("posts.create")
	r.Get("/posts/{id}/edit", web.H(h.Edit)).Name("posts.edit")
	r.Put("/posts/{id}", web.H(h.Update)).Name("posts.update")
	r.Delete("/posts/{id}", web.H(h.Delete)).Name("posts.delete")
}
```

A guest who opens `/posts/new` goes to the login page; a guest's post,
put or delete gets `401`: the login redirect is for pages. Hide the
buttons from guests with the shared `user`:

```vue
<!-- illustrative: frontend/src/pages/Posts/Index.vue, with const shared = usePage() -->
<LinkButton v-if="shared.props.user" :href="route('posts.new')">{{ t('posts.new') }}</LinkButton>
```

(The list's own prop is named `page`: name `usePage()`'s result
otherwise.)

Hiding a button isn't enough: the route's group is what keeps guests
out.

### 7. Test it

The tests are Go, and need neither Node nor a build: `AssertInertia`
checks the component, `AssertInertiaProp` a prop, by its path:

```go
// illustrative: drafts_test.go
package main

import (
	"testing"

	"anetos.dev/anetos/anetostest"
	"anetos.dev/anetos/db"

	"shop/app/models"
)

func TestDrafts(t *testing.T) {
	app := anetostest.New(t, setup)
	for _, p := range []models.Post{
		{Title: "Alpha", Body: "a"},
		{Title: "Beta", Body: "b"},
		{Title: "Out", Body: "c", Published: true},
	} {
		if err := db.Create(app.Context(), &p); err != nil {
			t.Fatal(err)
		}
	}
	app.Get("/drafts").AssertOK().AssertInertia("Posts/Drafts").
		AssertInertiaProp("posts.0.title", "Beta").AssertInertiaProp("drafts", 2)
	app.Get("/drafts?q=Alp").AssertInertiaProp("posts.0.title", "Alpha").AssertInertiaProp("q", "Alp")
}
```

With the posts behind a login (step 6), log a user in first:
`ada := anetostest.Create(app, factories.Users)` and
`anetostest.ActingAs(app, &ada)`. `go tool anetos check` runs the tests
and the frontend's build, whose `vue-tsc` type-checks every component,
templates included (on TypeScript 6: `vue-tsc` needs TypeScript's
JavaScript API, which TypeScript 7 doesn't have).

### 8. Build it

```sh
go tool anetos build   # bin/shop
```

It type-checks and builds the frontend into `public/build`, then the
binary, which embeds it: one file to deploy ([Deploy](https://docs.anetos.dev/main/guides/deployment/index.md)).

## Complete example

`anetos new --stack=vue` with `make:auth` and `make:crud` is the
complete example: its pages, handlers and tests are the patterns above.
[`examples/inertia`](https://github.com/anetos-dev/anetos/tree/main/examples/inertia), in React, shows more of
Inertia's props: deferred, merged and flashed.

## How it works

The first visit gets the HTML of `views/app.templ`, holding the page's
component and props; Inertia's client renders it inside the layout.
Later links and forms are requests that answer the next page's props as
JSON, and the client swaps the component in place. The routes, the
session, CSRF protection (an `XSRF-TOKEN` cookie the client sends back)
and validation are the web stack's.
[Pages in Vue, React or Svelte with Inertia](https://docs.anetos.dev/main/guides/inertia/index.md) covers the
protocol: partial reloads, deferred props, asset versions.

## Testing it

See step 7. The Go tests check what the handlers send; the type check
catches a component that reads a prop or route that isn't there. To
check a page in a browser, run the app with `go tool anetos dev`.

## Common problems

| Problem | Cause | Fix |
|---|---|---|
| The type check says a prop or a page doesn't exist | `frontend/src/types` is older than the Go code | `go run . types` (`anetos dev` does after each build) |
| `inertia: the page "Posts/Drafts" isn't in inertia.WithPages` | The page was made with `inertia.NewPage` instead of `page` | Declare it with `page[P]`, which lists it |
| `no page Posts/Drafts (frontend/src/pages/Posts/Drafts.vue)` in the browser's console | The component's file is missing or named differently | The file's path under `pages/` is the name in Go, with `.vue` |
| A key shows instead of its text (`posts.drafts.title`) | It isn't in `locales/en/` | Add it; the server sends the catalogs to the pages |

## Next steps

- [Pages in Vue, React or Svelte with Inertia](https://docs.anetos.dev/main/guides/inertia/index.md): the
  protocol, and the props that load later or merge.
- [Generate TypeScript types for the frontend](https://docs.anetos.dev/main/guides/typescript/index.md).
- [Move htmx pages to Inertia](https://docs.anetos.dev/main/guides/migrate-htmx-to-inertia/index.md), for a web
  project.
- [Frontends](https://docs.anetos.dev/main/concepts/frontends/index.md): the ways Anetos serves a
  frontend, and how to choose.
